@knowcode/doc-builder 1.4.25 → 1.5.1

package/.claude/settings.local.json

@@ -22,7 +22,8 @@
       "Bash(npm view:*)",
       "Bash(npm:*)",
       "Bash(vercel project:*)",
-      "Bash(vercel alias:*)"
+      "Bash(vercel alias:*)",
+      "Bash(find:*)"
     ],
     "deny": []
   }

package/CHANGELOG.md

@@ -5,6 +5,58 @@ 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.1] - 2025-07-21
+
+### Added
+- Automatic redirect from .md URLs to their corresponding .html files
+- Client-side JavaScript to intercept clicks on .md links and redirect to .html
+- Custom 404.html page with automatic redirect logic for direct .md URL navigation
+- Enhanced vercel.json generation to include 404 page routing
+
+### Fixed
+- Fixed 404 errors when clicking or navigating to .md links
+- Links like `claude-workflow-guide.md` now automatically redirect to `claude-workflow-guide.html`
+
+### Background
+- Users reported that links to .md files resulted in 404 errors
+- Implemented client-side solution to handle both link clicks and direct navigation
+- Works seamlessly with Vercel's cleanUrls configuration
+
+## [1.5.0] - 2025-07-21
+
+### Added
+- Comprehensive SEO features including meta tags, Open Graph, Twitter Cards
+- JSON-LD structured data for better search engine understanding
+- Automatic sitemap.xml and robots.txt generation
+- Interactive `setup-seo` CLI command to configure SEO settings
+- SEO configuration options in doc-builder.config.js
+- Production URL configuration with `set-production-url` command
+- Support for custom production URLs via config file, CLI command, or deployment flag
+
+### Improved
+- Better deployment URL detection with multiple fallback methods
+- Enhanced meta tag generation with author, keywords, and canonical URLs
+- Social media preview support with customizable images and descriptions
+
+### Documentation
+- Added comprehensive SEO guide explaining all features and configuration
+- Updated troubleshooting guide with npx cache clearing instructions
+
+## [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

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/assets/404.html

@@ -0,0 +1,115 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Page Not Found - Redirecting...</title>
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
+    <style>
+        body {
+            font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+            margin: 0;
+            padding: 0;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            min-height: 100vh;
+            background-color: #f7f7f5;
+            color: #37352f;
+        }
+        .container {
+            text-align: center;
+            padding: 2rem;
+            max-width: 600px;
+        }
+        h1 {
+            font-size: 3rem;
+            margin: 0 0 1rem 0;
+            color: #37352f;
+        }
+        p {
+            font-size: 1.125rem;
+            line-height: 1.6;
+            color: #6b6b6b;
+            margin: 0 0 2rem 0;
+        }
+        a {
+            color: #0366d6;
+            text-decoration: none;
+        }
+        a:hover {
+            text-decoration: underline;
+        }
+        .emoji {
+            font-size: 4rem;
+            margin-bottom: 1rem;
+        }
+        .loading {
+            display: none;
+            color: #0366d6;
+            margin-top: 1rem;
+        }
+        .redirect-message {
+            display: none;
+            background-color: #e8f4fd;
+            border: 1px solid #c3e0f7;
+            padding: 1rem;
+            border-radius: 8px;
+            margin-top: 1rem;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div class="emoji">🔍</div>
+        <h1>404</h1>
+        <p id="message">The page you're looking for doesn't exist.</p>
+        <div id="redirect-message" class="redirect-message">
+            Redirecting to the correct page...
+        </div>
+        <p id="loading" class="loading">Redirecting...</p>
+        <p>
+            <a href="/" id="home-link">Go to Home</a>
+        </p>
+    </div>
+
+    <script>
+        // Check if the URL ends with .md
+        const pathname = window.location.pathname;
+        
+        if (pathname.endsWith('.md')) {
+            // Convert .md to .html
+            const htmlPath = pathname.replace(/\.md$/, '.html');
+            
+            // Show redirect message
+            document.getElementById('message').textContent = 'Found a markdown link. Redirecting to the HTML version...';
+            document.getElementById('redirect-message').style.display = 'block';
+            document.getElementById('loading').style.display = 'block';
+            
+            // Redirect after a brief delay to show the message
+            setTimeout(() => {
+                window.location.replace(htmlPath);
+            }, 500);
+        } else {
+            // For true 404s, show the standard message
+            document.getElementById('message').textContent = "The page you're looking for doesn't exist.";
+            
+            // Also check if we can suggest a similar page
+            // Remove common suffixes and try to find a match
+            const basePath = pathname
+                .replace(/\.(html|htm|php|asp|aspx)$/, '')
+                .replace(/\/$/, '');
+            
+            if (basePath && basePath !== pathname) {
+                document.getElementById('message').innerHTML = 
+                    `The page you're looking for doesn't exist.<br>
+                     <small>Did you mean <a href="${basePath}.html">${basePath}.html</a>?</small>`;
+            }
+        }
+        
+        // Update home link to use the correct base URL
+        const baseUrl = window.location.origin;
+        document.getElementById('home-link').href = baseUrl;
+    </script>
+</body>
+</html>

package/assets/js/main.js

@@ -1318,8 +1318,31 @@ function initTooltips() {
   });
 }
 
+// Handle .md link redirects
+function initMarkdownLinkRedirects() {
+  // Check if current URL ends with .md and redirect
+  if (window.location.pathname.endsWith('.md')) {
+    const htmlPath = window.location.pathname.replace(/\.md$/, '.html');
+    console.log(`Redirecting from .md to .html: ${htmlPath}`);
+    window.location.replace(htmlPath);
+    return; // Stop execution as we're redirecting
+  }
+  
+  // Intercept clicks on .md links
+  document.addEventListener('click', function(e) {
+    const link = e.target.closest('a');
+    if (link && link.href && link.href.endsWith('.md')) {
+      e.preventDefault();
+      const htmlUrl = link.href.replace(/\.md$/, '.html');
+      console.log(`Converting .md link to .html: ${htmlUrl}`);
+      window.location.href = htmlUrl;
+    }
+  });
+}
+
 // Initialize on DOM Load
 document.addEventListener('DOMContentLoaded', () => {
+  initMarkdownLinkRedirects();
   highlightNavigation();
   generateTableOfContents();
   initSidebarResize();

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,34 @@
+module.exports = {
+  "siteName": "Doc Builder",
+  "siteDescription": "Beautiful documentation with the least effort possible",
+  "docsDir": "docs",
+  "outputDir": "html",
+  "productionUrl": "https://doc-builder-delta.vercel.app",
+  "features": {
+    "authentication": false,
+    "changelog": true,
+    "mermaid": true,
+    "darkMode": true
+  },
+  "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"
+    ],
+    "generateSitemap": true,
+    "generateRobotsTxt": true,
+    "ogImage": "/og-default.png",
+    "organization": {
+      "name": "Knowcode Ltd",
+      "url": "https://knowcode.tech"
+    }
+  }
+};