@knowcode/doc-builder 1.4.24 → 1.5.0

package/.claude/settings.local.json

@@ -20,7 +20,10 @@
       "Bash(ls:*)",
       "Bash(npm run build:*)",
       "Bash(npm view:*)",
-      "Bash(npm:*)"
+      "Bash(npm:*)",
+      "Bash(vercel project:*)",
+      "Bash(vercel alias:*)",
+      "Bash(find:*)"
     ],
     "deny": []
   }

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.4.26] - 2025-07-21
+
+### Improved
+- Clarified Vercel setup instructions to show both paths for question #5
+- Now clearly indicates what prompt users see based on their answer to question #4
+- Added "If you answered YES/NO to #4" conditional guidance
+- Shows appropriate project name prompts for both existing and new projects
+
+### Background
+- Users were confused about what happens after answering NO to "Link to different existing project?"
+- The instructions now clearly show both scenarios:
+  - YES: "What's the name of your existing project?"
+  - NO: "What is your project name?" (for creating new project)
+- This matches the actual Vercel CLI flow more accurately
+
+## [1.4.25] - 2025-07-21
+
+### Fixed
+- Improved production URL detection with multiple fallback methods
+- Tries to extract project name and construct standard Vercel URL
+- Better handling of different Vercel URL formats
+
+### Background
+- Previous version didn't correctly parse Vercel's output
+- Now uses multiple methods to determine the production URL
+- Extracts project name from deployment URL as fallback
+
 ## [1.4.24] - 2025-07-21
 
 ### Fixed

package/README.md

@@ -54,6 +54,7 @@ This aligns perfectly with our mission: beautiful documentation should be access
 - 🌙 **Dark Mode** - Automatic dark mode support
 - 🔄 **Live Reload** - Development server with hot reloading
 - ☁️ **Vercel Integration** - One-command deployment to Vercel
+- 🔍 **SEO Optimized** - Meta tags, Open Graph, Twitter Cards, and structured data
 - 📦 **Self-Contained** - No configuration or setup required
 - 🤖 **Claude Code Ready** - Optimized for AI-generated documentation workflows
 
@@ -119,6 +120,9 @@ module.exports = {
   siteName: 'My Documentation',
   siteDescription: 'Documentation for my project',
   
+  // Production URL (optional)
+  productionUrl: 'https://my-docs.vercel.app',  // Custom URL to display after deployment
+  
   // Features
   features: {
     authentication: true,
@@ -145,6 +149,33 @@ npx @knowcode/doc-builder build --preset notion-inspired
 
 ## Commands
 
+### set-production-url
+Set a custom production URL to display after deployment:
+```bash
+# Set your custom production URL
+npx @knowcode/doc-builder set-production-url doc-builder-delta.vercel.app
+
+# Or with full protocol
+npx @knowcode/doc-builder set-production-url https://my-custom-domain.com
+```
+
+This is useful when you have a custom domain or Vercel alias that differs from the auto-detected URL.
+
+### setup-seo
+Interactive SEO configuration wizard:
+```bash
+# Configure all SEO settings
+npx @knowcode/doc-builder setup-seo
+```
+
+This wizard helps you set up:
+- Site URL and author information
+- Social media meta tags (Open Graph, Twitter Cards)
+- Structured data (JSON-LD)
+- Automatic sitemap and robots.txt generation
+
+See the [SEO Guide](docs/guides/seo-guide.md) for complete details.
+
 ### build
 Build the documentation site to static HTML:
 ```bash
@@ -189,15 +220,15 @@ Deploy documentation to Vercel (requires Vercel CLI):
 doc-builder deploy [options]
 
 Options:
-  -c, --config <path>  Path to config file (default: "doc-builder.config.js")
-  --prod               Deploy to production (default: preview deployment)
-  --no-build           Skip building before deployment
-  --force              Force deployment without confirmation
+  -c, --config <path>         Path to config file (default: "doc-builder.config.js")
+  --no-prod                   Deploy as preview instead of production
+  --force                     Force deployment without confirmation
+  --production-url <url>      Override production URL for this deployment
 
 Examples:
-  doc-builder deploy                 # Deploy preview to Vercel
-  doc-builder deploy --prod          # Deploy to production
-  doc-builder deploy --no-build      # Deploy existing build
+  doc-builder deploy                                    # Deploy to production
+  doc-builder deploy --no-prod                          # Deploy as preview only
+  doc-builder deploy --production-url my-docs.vercel.app  # Use custom URL display
 
 First-time setup:
   The tool will guide you through:
@@ -324,6 +355,25 @@ npx @knowcode/doc-builder@1.4.22
 - Ensure Vercel CLI is installed: `npm install -g vercel`
 - Check that the `html/` directory was created by build command
 
+**Wrong production URL displayed**
+- The deployment may show a deployment-specific URL instead of your custom domain
+- Solution 1: Set production URL in config:
+  ```javascript
+  // doc-builder.config.js
+  module.exports = {
+    productionUrl: 'https://my-docs.vercel.app',
+    // ... other config
+  };
+  ```
+- Solution 2: Use command to set it:
+  ```bash
+  npx @knowcode/doc-builder set-production-url my-docs.vercel.app
+  ```
+- Solution 3: Override for a single deployment:
+  ```bash
+  npx @knowcode/doc-builder deploy --production-url my-docs.vercel.app
+  ```
+
 ## Using in Other Projects
 
 ### Option 1: NPM Link (Development)

package/cli.js

@@ -118,6 +118,67 @@ ${chalk.yellow('Examples:')}
     }
   });
 
+// Set Production URL command
+program
+  .command('set-production-url <url>')
+  .description('Set the production URL to display after deployment')
+  .option('-c, --config <path>', 'path to config file (default: doc-builder.config.js)')
+  .addHelpText('after', `
+${chalk.yellow('Examples:')}
+  ${chalk.gray('$')} doc-builder set-production-url doc-builder-delta.vercel.app
+  ${chalk.gray('$')} doc-builder set-production-url https://my-custom-domain.com
+
+${chalk.yellow('This URL will be displayed after deployment instead of auto-detected URLs.')}
+`)
+  .action(async (url, options) => {
+    try {
+      const configPath = path.join(process.cwd(), options.config || 'doc-builder.config.js');
+      
+      // Ensure URL has protocol
+      if (!url.startsWith('http')) {
+        url = 'https://' + url;
+      }
+      
+      if (fs.existsSync(configPath)) {
+        // Update existing config
+        let configContent = fs.readFileSync(configPath, 'utf8');
+        
+        if (configContent.includes('productionUrl:')) {
+          // Update existing productionUrl
+          configContent = configContent.replace(
+            /productionUrl:\s*['"][^'"]*['"]/,
+            `productionUrl: '${url}'`
+          );
+        } else {
+          // Add productionUrl to config
+          configContent = configContent.replace(
+            /module\.exports = {/,
+            `module.exports = {\n  productionUrl: '${url}',`
+          );
+        }
+        
+        fs.writeFileSync(configPath, configContent);
+        console.log(chalk.green(`✅ Production URL set to: ${url}`));
+        console.log(chalk.gray(`\nThis URL will be displayed after deployment.`));
+      } else {
+        console.log(chalk.yellow('⚠️  No config file found. Creating one...'));
+        await createDefaultConfig();
+        
+        // Add production URL to newly created config
+        let configContent = fs.readFileSync(configPath, 'utf8');
+        configContent = configContent.replace(
+          /module\.exports = {/,
+          `module.exports = {\n  productionUrl: '${url}',`
+        );
+        fs.writeFileSync(configPath, configContent);
+        console.log(chalk.green(`✅ Created config with production URL: ${url}`));
+      }
+    } catch (error) {
+      console.error(chalk.red('Failed to set production URL:'), error.message);
+      process.exit(1);
+    }
+  });
+
 // Deploy command
 program
   .command('deploy')
@@ -125,6 +186,7 @@ program
   .option('-c, --config <path>', 'path to config file (default: doc-builder.config.js)')
   .option('--no-prod', 'deploy as preview instead of production')
   .option('--force', 'force deployment without confirmation')
+  .option('--production-url <url>', 'override production URL for this deployment')
   .addHelpText('after', `
 ${chalk.yellow('Examples:')}
   ${chalk.gray('$')} doc-builder deploy                 ${chalk.gray('# Deploy to production')}
@@ -267,6 +329,13 @@ ${chalk.yellow('Troubleshooting:')}
         process.exit(1);
       }
       
+      // Handle production URL option
+      if (options.productionUrl) {
+        config.productionUrl = options.productionUrl.startsWith('http') 
+          ? options.productionUrl 
+          : 'https://' + options.productionUrl;
+      }
+      
       // Always build first
       spinner.stop();
       console.log(chalk.blue('\n📦 Building documentation first...\n'));
@@ -329,8 +398,8 @@ ${chalk.yellow('Troubleshooting:')}
         productionUrl = result.productionUrl;
       }
       
-      // Use the production URL if available, otherwise show the deployment URL
-      const displayUrl = productionUrl || deployUrl;
+      // Use the configured production URL if available, then detected, then deployment URL
+      const displayUrl = config.productionUrl || productionUrl || deployUrl;
       
       console.log(chalk.green('\n✅ Deployment Complete!\n'));
       
@@ -407,6 +476,186 @@ ${chalk.yellow('When to use:')}
     }
   });
 
+// Setup SEO command
+program
+  .command('setup-seo')
+  .description('Configure SEO settings for your documentation')
+  .option('-c, --config <path>', 'path to config file (default: doc-builder.config.js)')
+  .addHelpText('after', `
+${chalk.yellow('What this does:')}
+  • Configures meta tags for search engines
+  • Sets up social media previews (Open Graph, Twitter Cards)
+  • Enables automatic sitemap.xml generation
+  • Creates robots.txt for search engines
+  • Adds structured data (JSON-LD)
+
+${chalk.yellow('What you\'ll configure:')}
+  • Site URL (your production URL)
+  • Author name and organization
+  • Twitter handle for social cards
+  • Default keywords
+  • Open Graph image
+
+${chalk.yellow('After setup:')}
+  • Run ${chalk.cyan('npx @knowcode/doc-builder build')} to generate with SEO
+  • Check meta tags in generated HTML files
+  • Submit sitemap.xml to search engines
+`)
+  .action(async (options) => {
+    try {
+      const configPath = path.join(process.cwd(), options.config || 'doc-builder.config.js');
+      let config = {};
+      
+      // Load existing config if it exists
+      if (fs.existsSync(configPath)) {
+        try {
+          delete require.cache[require.resolve(configPath)];
+          config = require(configPath);
+        } catch (e) {
+          console.log(chalk.yellow('⚠️  Could not load existing config, starting fresh'));
+        }
+      }
+      
+      console.log(chalk.blue('\n🔍 SEO Setup for @knowcode/doc-builder\n'));
+      console.log(chalk.gray('This wizard will help you configure SEO settings for better search engine visibility.\n'));
+      
+      // Interactive prompts
+      const answers = await prompts([
+        {
+          type: 'text',
+          name: 'siteUrl',
+          message: 'What is your site\'s URL?',
+          initial: config.seo?.siteUrl || config.productionUrl || 'https://my-docs.vercel.app',
+          validate: value => {
+            try {
+              new URL(value);
+              return true;
+            } catch {
+              return 'Please enter a valid URL (e.g., https://example.com)';
+            }
+          }
+        },
+        {
+          type: 'text',
+          name: 'author',
+          message: 'Author name?',
+          initial: config.seo?.author || ''
+        },
+        {
+          type: 'text',
+          name: 'twitterHandle',
+          message: 'Twitter handle?',
+          initial: config.seo?.twitterHandle || '',
+          format: value => {
+            if (!value) return '';
+            return value.startsWith('@') ? value : '@' + value;
+          }
+        },
+        {
+          type: 'text',
+          name: 'language',
+          message: 'Site language?',
+          initial: config.seo?.language || 'en-US'
+        },
+        {
+          type: 'text',
+          name: 'organizationName',
+          message: 'Organization name (optional)?',
+          initial: config.seo?.organization?.name || ''
+        },
+        {
+          type: prev => prev ? 'text' : null,
+          name: 'organizationUrl',
+          message: 'Organization URL?',
+          initial: config.seo?.organization?.url || ''
+        },
+        {
+          type: 'text',
+          name: 'ogImage',
+          message: 'Default Open Graph image URL/path?',
+          initial: config.seo?.ogImage || '/og-default.png',
+          hint: 'Recommended: 1200x630px PNG or JPG'
+        },
+        {
+          type: 'text',
+          name: 'keywords',
+          message: 'Site keywords (comma-separated)?',
+          initial: Array.isArray(config.seo?.keywords) ? config.seo.keywords.join(', ') : 'documentation, guide, api'
+        },
+        {
+          type: 'confirm',
+          name: 'generateSitemap',
+          message: 'Generate sitemap.xml?',
+          initial: config.seo?.generateSitemap !== false
+        },
+        {
+          type: 'confirm',
+          name: 'generateRobotsTxt',
+          message: 'Generate robots.txt?',
+          initial: config.seo?.generateRobotsTxt !== false
+        }
+      ]);
+      
+      // Build SEO config
+      const seoConfig = {
+        enabled: true,
+        siteUrl: answers.siteUrl,
+        author: answers.author,
+        twitterHandle: answers.twitterHandle,
+        language: answers.language,
+        keywords: answers.keywords.split(',').map(k => k.trim()).filter(k => k),
+        generateSitemap: answers.generateSitemap,
+        generateRobotsTxt: answers.generateRobotsTxt,
+        ogImage: answers.ogImage
+      };
+      
+      // Add organization if provided
+      if (answers.organizationName) {
+        seoConfig.organization = {
+          name: answers.organizationName,
+          url: answers.organizationUrl || answers.siteUrl
+        };
+      }
+      
+      // Update config
+      config.seo = seoConfig;
+      
+      // Also update productionUrl if not set
+      if (!config.productionUrl && answers.siteUrl) {
+        config.productionUrl = answers.siteUrl;
+      }
+      
+      // Write config file
+      const configContent = `module.exports = ${JSON.stringify(config, null, 2)};\n`;
+      fs.writeFileSync(configPath, configContent);
+      
+      console.log(chalk.green('\n✅ SEO configuration saved to ' + path.basename(configPath)));
+      
+      console.log(chalk.blue('\nYour documentation will now include:'));
+      console.log(chalk.gray('• Meta tags for search engines'));
+      console.log(chalk.gray('• Open Graph tags for social media previews'));
+      console.log(chalk.gray('• Twitter Card tags for Twitter sharing'));
+      console.log(chalk.gray('• JSON-LD structured data'));
+      if (answers.generateSitemap) {
+        console.log(chalk.gray('• Automatic sitemap.xml generation'));
+      }
+      if (answers.generateRobotsTxt) {
+        console.log(chalk.gray('• robots.txt for crawler instructions'));
+      }
+      
+      console.log(chalk.yellow('\n💡 Tips:'));
+      if (answers.ogImage) {
+        console.log(chalk.gray(`- Add an image at ${answers.ogImage} (1200x630px) for social previews`));
+      }
+      console.log(chalk.gray('- Run \'npx @knowcode/doc-builder build\' to generate with SEO'));
+      console.log(chalk.gray('- Check your SEO at: https://metatags.io'));
+      
+    } catch (error) {
+      console.error(chalk.red('Failed to configure SEO:'), error.message);
+      process.exit(1);
+    }
+  });
+
 // Init command
 program
   .command('init')

package/doc-builder.config.js

@@ -0,0 +1,38 @@
+module.exports = {
+  // Site info
+  siteName: 'Doc Builder',
+  siteDescription: 'Beautiful documentation with the least effort possible',
+  
+  // Directories
+  docsDir: 'docs',
+  outputDir: 'html',
+  
+  // Production URL
+  productionUrl: 'https://doc-builder-delta.vercel.app',
+  
+  // Features
+  features: {
+    authentication: false,
+    changelog: true,
+    mermaid: true,
+    darkMode: true
+  },
+  
+  // SEO configuration
+  seo: {
+    enabled: true,
+    siteUrl: 'https://doc-builder-delta.vercel.app',
+    author: 'Lindsay Smith',
+    twitterHandle: '@planbbackups',
+    language: 'en-US',
+    keywords: ['documentation', 'markdown', 'static site generator', 'vercel', 'notion-style'],
+    organization: {
+      name: 'KnowCode',
+      url: 'https://knowcode.com'
+    },
+    ogImage: '/og-default.png',
+    generateSitemap: true,
+    generateRobotsTxt: true,
+    customMetaTags: []
+  }
+};

package/html/README.html

@@ -3,8 +3,30 @@
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <meta name="description" content="Documentation site built with @knowcode/doc-builder">
-    <title>@knowcode/doc-builder - Documentation</title>
+    <meta name="description" content="@knowcode/doc-builder.">
+    <title>@knowcode/doc-builder - Doc Builder</title>
+    
+    <meta name="author" content="Lindsay Smith">
+    <meta name="keywords" content="documentation, markdown, static site generator, vercel, notion-style, your, knowcode, doc, builder">
+    <meta name="robots" content="index, follow">
+    <link rel="canonical" href="https://doc-builder-delta.vercel.app/README.html">
+    
+    <!-- Open Graph / Facebook -->
+    <meta property="og:type" content="article">
+    <meta property="og:url" content="https://doc-builder-delta.vercel.app/README.html">
+    <meta property="og:title" content="@knowcode/doc-builder - Doc Builder">
+    <meta property="og:description" content="@knowcode/doc-builder.">
+    <meta property="og:image" content="https://doc-builder-delta.vercel.app/og-default.png">
+    <meta property="og:site_name" content="Doc Builder">
+    <meta property="og:locale" content="en_US">
+    
+    <!-- Twitter Card -->
+    <meta name="twitter:card" content="summary_large_image">
+    <meta name="twitter:site" content="@planbbackups">
+    <meta name="twitter:creator" content="@planbbackups">
+    <meta name="twitter:title" content="@knowcode/doc-builder - Doc Builder">
+    <meta name="twitter:description" content="@knowcode/doc-builder.">
+    <meta name="twitter:image" content="https://doc-builder-delta.vercel.app/og-default.png">
     
     <!-- Fonts -->
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
@@ -20,16 +42,57 @@
     
     <!-- Favicon -->
     <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>📚</text></svg>">
+    
+    <script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "TechArticle",
+  "headline": "@knowcode/doc-builder",
+  "description": "@knowcode/doc-builder.",
+  "author": {
+    "@type": "Person",
+    "name": "Lindsay Smith"
+  },
+  "publisher": {
+    "@type": "Organization",
+    "name": "KnowCode",
+    "url": "https://knowcode.com"
+  },
+  "datePublished": "2025-07-21T20:24:35.105Z",
+  "dateModified": "2025-07-21T20:24:35.105Z",
+  "mainEntityOfPage": {
+    "@type": "WebPage",
+    "@id": "https://doc-builder-delta.vercel.app/README.html"
+  },
+  "breadcrumb": {
+    "@type": "BreadcrumbList",
+    "itemListElement": [
+      {
+        "@type": "ListItem",
+        "position": 1,
+        "name": "Doc Builder",
+        "item": "https://doc-builder-delta.vercel.app"
+      },
+      {
+        "@type": "ListItem",
+        "position": 2,
+        "name": "README",
+        "item": "https://doc-builder-delta.vercel.app/README.html"
+      }
+    ]
+  }
+}
+</script>
 </head>
 <body>
     <!-- Header -->
     <header class="header">
         <div class="header-content">
-            <a href="/index.html" class="logo">Documentation</a>
+            <a href="/index.html" class="logo">Doc Builder</a>
             
             <div class="header-actions">
                 <div class="deployment-info">
-                    <span class="deployment-date" title="Built with doc-builder v1.4.23">Last updated: Jul 21, 2025, 07:42 PM UTC</span>
+                    <span class="deployment-date" title="Built with doc-builder v1.4.26">Last updated: Jul 21, 2025, 08:24 PM UTC</span>
                 </div>
                 
                 
@@ -80,7 +143,9 @@
         <div class="nav-content" >
         <a href="/README.html" class="nav-item active" data-tooltip="@knowcode/doc-builder."><i class="fas fa-file-alt"></i> Overview</a>
         <a href="/claude-workflow-guide.html" class="nav-item" data-tooltip="This guide demonstrates an efficient workflow for using Claude Code with a refined CLAUDE.md file to create high-quality documentation and deploy it..."><i class="fas fa-file-alt"></i> Claude Workflow Guide</a>
-        <a href="/documentation-index.html" class="nav-item" data-tooltip="This directory contains additional documentation for the @knowcode/doc-builder project, organized by topic and purpose."><i class="fas fa-file-alt"></i> Documentation Index</a></div></div>
+        <a href="/documentation-index.html" class="nav-item" data-tooltip="This directory contains additional documentation for the @knowcode/doc-builder project, organized by topic and purpose."><i class="fas fa-file-alt"></i> Documentation Index</a>
+        <a href="/vercel-cli-setup-guide.html" class="nav-item" data-tooltip="This guide provides comprehensive instructions for installing and configuring the Vercel CLI across different operating systems and environments."><i class="fas fa-file-alt"></i> Vercel Cli Setup Guide</a>
+        <a href="/vercel-first-time-setup-guide.html" class="nav-item" data-tooltip="This guide provides a detailed explanation of every prompt you&#039;ll encounter during the first-time Vercel setup process when using."><i class="fas fa-file-alt"></i> Vercel First Time Setup Guide</a></div></div>
       <div class="nav-section" data-level="1">
         <a class="nav-title collapsible expanded" href="#" data-target="nav-guides-1" >
           <i class="fas fa-chevron-right collapse-icon"></i><i class="fas fa-folder"></i> Guides
@@ -88,6 +153,7 @@
         <div class="nav-content" id="nav-guides-1">
         <a href="/guides/authentication-guide.html" class="nav-item" data-tooltip="This guide explains how to configure and use the built-in authentication feature in @knowcode/doc-builder to protect your documentation with basic..."><i class="fas fa-file-alt"></i> Authentication Guide</a>
         <a href="/guides/documentation-standards.html" class="nav-item" data-tooltip="This document defines the documentation standards and conventions for the @knowcode/doc-builder project."><i class="fas fa-file-alt"></i> Documentation Standards</a>
+        <a href="/guides/seo-guide.html" class="nav-item" data-tooltip="@knowcode/doc-builder includes comprehensive SEO (Search Engine Optimization) features to help your documentation rank better in search results and..."><i class="fas fa-file-alt"></i> Seo Guide</a>
         <a href="/guides/troubleshooting-guide.html" class="nav-item" data-tooltip="This guide helps you resolve common issues when using @knowcode/doc-builder."><i class="fas fa-file-alt"></i> Troubleshooting Guide</a></div></div>
             </nav>
             <div class="resize-handle"></div>