@knowcode/doc-builder 1.4.21 → 1.4.24

package/.claude/settings.local.json

@@ -19,7 +19,8 @@
       "Bash(npm cache clean:*)",
       "Bash(ls:*)",
       "Bash(npm run build:*)",
-      "Bash(npm view:*)"
+      "Bash(npm view:*)",
+      "Bash(npm:*)"
     ],
     "deny": []
   }

package/CHANGELOG.md

@@ -5,6 +5,44 @@ 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.24] - 2025-07-21
+
+### Fixed
+- Deployment now shows the correct production URL from Vercel
+- Uses Vercel CLI to fetch the actual production alias
+- Shows clean URL like `doc-builder-delta.vercel.app` instead of deployment URL
+
+### Background
+- Previously showed deployment URLs like `doc-builder-i02vs7dur-lindsay-1340s-projects.vercel.app`
+- Now queries `vercel project ls` to get the actual production URL
+- Falls back to deployment URL if production URL cannot be determined
+
+## [1.4.23] - 2025-07-21
+
+### Added
+- Added npx cache clearing instructions to CLI help
+- Added troubleshooting section to README
+- Created comprehensive troubleshooting guide
+- Documented `npx clear-npx-cache` solution prominently
+
+### Background
+- Users frequently encounter npx cache issues causing old versions to run
+- The npx cache doesn't automatically update when new versions are published
+- This causes confusion when bug fixes or new features don't appear
+- Clear documentation helps users resolve this common issue quickly
+
+## [1.4.22] - 2025-07-21
+
+### Fixed
+- Fixed incorrect production URL display after deployment
+- Deployment now shows the actual Vercel URL instead of truncated version
+
+### Background
+- The regex pattern was only capturing text before the first hyphen
+- For `doc-builder-delta.vercel.app` it showed `doc.vercel.app`
+- Now properly displays the full production URL returned by Vercel
+- Also handles preview URLs with random suffixes correctly
+
 ## [1.4.21] - 2025-07-21
 
 ### Fixed

package/README.md

@@ -280,6 +280,50 @@ When using Claude Code to generate documentation, it typically follows these pat
 - **Review Generated Content**: Always review AI-generated documentation for accuracy
 - **Maintain CLAUDE.md**: Keep project-specific instructions in a CLAUDE.md file for consistent documentation style
 
+## Troubleshooting
+
+### NPX Cache Issues
+
+The npx command caches packages to speed up subsequent runs. However, this can sometimes cause you to run an older version even after updating. 
+
+**Symptoms:**
+- Running `npx @knowcode/doc-builder` shows an old version number
+- New features aren't available despite updating
+- Changes don't appear after publishing a new version
+
+**Solution:**
+```bash
+# Clear the npx cache
+npx clear-npx-cache
+
+# Force the latest version
+npx @knowcode/doc-builder@latest
+
+# Or specify an exact version
+npx @knowcode/doc-builder@1.4.22
+```
+
+**Prevention:**
+- Always use `@latest` when you want the newest version
+- Clear cache periodically when developing/testing new versions
+- Use `npm install` for projects where you need a specific version
+
+### Other Common Issues
+
+**"Command not found" error**
+- Ensure Node.js 14+ is installed: `node --version`
+- Try with full package name: `npx @knowcode/doc-builder`
+
+**Build fails with "No markdown files found"**
+- Check that your docs are in the `docs/` folder (or specified input directory)
+- Ensure files have `.md` extension
+- Use `--input` flag to specify a different directory
+
+**Vercel deployment fails**
+- Run `npx @knowcode/doc-builder reset-vercel` to clear settings
+- Ensure Vercel CLI is installed: `npm install -g vercel`
+- Check that the `html/` directory was created by build command
+
 ## Using in Other Projects
 
 ### Option 1: NPM Link (Development)

package/assets/css/notion-style.css

@@ -974,7 +974,7 @@ tr:hover {
   
   .content {
     margin-left: 0;
-    padding: var(--space-6) var(--space-4);
+    padding: var(--space-3) var(--space-4); /* Reduced top/bottom padding on mobile */
   }
   
   .menu-toggle {
@@ -1596,7 +1596,7 @@ tr:hover {
   /* Sidebar positioning handled in earlier media query */
   
   .content {
-    padding: var(--space-4);
+    padding: var(--space-3) var(--space-4); /* Consistent reduced padding on mobile */
   }
   
   .content-inner {
@@ -1609,10 +1609,7 @@ tr:hover {
     padding: 0 var(--space-4);
   }
   
-  .preview-banner {
-    position: relative;
-    top: 0;
-  }
+  /* Keep preview banner fixed on mobile */
   
   /* Keep breadcrumbs fixed on mobile to prevent double spacing */
 }

package/cli.js

@@ -48,6 +48,11 @@ ${chalk.yellow('Quick Start:')}
      ${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.yellow('Troubleshooting npx cache issues:')}
+  ${chalk.red('If you see an old version after updating:')}
+     ${chalk.gray('$')} npx clear-npx-cache                    ${chalk.gray('# Clear the npx cache')}
+     ${chalk.gray('$')} npx @knowcode/doc-builder@latest       ${chalk.gray('# Force latest version')}
      ${chalk.gray('$')} npx @knowcode/doc-builder dev          ${chalk.gray('# Start development server')}
 
 ${chalk.yellow('No docs folder yet?')}
@@ -309,24 +314,38 @@ ${chalk.yellow('Troubleshooting:')}
       spinner.start('Deploying to Vercel...');
       // Default to production deployment
       const isProduction = options.prod !== false;  // Default true unless explicitly --no-prod
-      const url = await deployToVercel(config, isProduction);
+      const result = await deployToVercel(config, isProduction);
       spinner.succeed(`Deployed successfully!`);
       
-      // Extract project name from URL
-      const projectName = url.match(/https:\/\/([^-]+)/)?.[1] || 'your-project';
+      // Handle both old and new return formats
+      let deployUrl, productionUrl;
+      if (typeof result === 'string') {
+        // Old format - just a URL string
+        deployUrl = result;
+        productionUrl = null;
+      } else {
+        // New format - object with deployUrl and productionUrl
+        deployUrl = result.deployUrl;
+        productionUrl = result.productionUrl;
+      }
+      
+      // Use the production URL if available, otherwise show the deployment URL
+      const displayUrl = productionUrl || deployUrl;
       
       console.log(chalk.green('\n✅ Deployment Complete!\n'));
       
       if (isProduction) {
         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(chalk.cyan.bold(`   ${displayUrl}`) + 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)'));
+        if (productionUrl && deployUrl && productionUrl !== deployUrl) {
+          console.log(chalk.gray('This deployment also created a unique preview URL:'));
+          console.log(chalk.gray(`   ${deployUrl}`));
+          console.log(chalk.gray('   (This URL is specific to this deployment)'));
+        }
       } else {
         console.log(chalk.yellow('🔍 Preview deployment created at:'));
-        console.log(chalk.cyan(`   ${url}`));
+        console.log(chalk.cyan(`   ${deployUrl}`));
         console.log();
         console.log(chalk.gray('To deploy to production, run:'));
         console.log(chalk.gray('   npx @knowcode/doc-builder deploy'));

package/html/README.html

@@ -29,7 +29,7 @@
             
             <div class="header-actions">
                 <div class="deployment-info">
-                    <span class="deployment-date" title="Built with doc-builder v1.4.21">Last updated: Jul 21, 2025, 06:12 PM UTC</span>
+                    <span class="deployment-date" title="Built with doc-builder v1.4.23">Last updated: Jul 21, 2025, 07:42 PM UTC</span>
                 </div>
                 
                 
@@ -86,7 +86,9 @@
           <i class="fas fa-chevron-right collapse-icon"></i><i class="fas fa-folder"></i> Guides
         </a>
         <div class="nav-content" id="nav-guides-1">
-        <a href="/guides/DOCUMENT-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> DOCUMENT STANDARDS</a></div></div>
+        <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/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>
         </aside>

package/html/claude-workflow-guide.html

@@ -29,7 +29,7 @@
             
             <div class="header-actions">
                 <div class="deployment-info">
-                    <span class="deployment-date" title="Built with doc-builder v1.4.21">Last updated: Jul 21, 2025, 06:12 PM UTC</span>
+                    <span class="deployment-date" title="Built with doc-builder v1.4.23">Last updated: Jul 21, 2025, 07:42 PM UTC</span>
                 </div>
                 
                 
@@ -86,7 +86,9 @@
           <i class="fas fa-chevron-right collapse-icon"></i><i class="fas fa-folder"></i> Guides
         </a>
         <div class="nav-content collapsed" id="nav-guides-1">
-        <a href="/guides/DOCUMENT-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> DOCUMENT STANDARDS</a></div></div>
+        <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/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>
         </aside>

package/html/css/notion-style.css

@@ -974,7 +974,7 @@ tr:hover {
   
   .content {
     margin-left: 0;
-    padding: var(--space-6) var(--space-4);
+    padding: var(--space-3) var(--space-4); /* Reduced top/bottom padding on mobile */
   }
   
   .menu-toggle {
@@ -1596,7 +1596,7 @@ tr:hover {
   /* Sidebar positioning handled in earlier media query */
   
   .content {
-    padding: var(--space-4);
+    padding: var(--space-3) var(--space-4); /* Consistent reduced padding on mobile */
   }
   
   .content-inner {
@@ -1609,10 +1609,7 @@ tr:hover {
     padding: 0 var(--space-4);
   }
   
-  .preview-banner {
-    position: relative;
-    top: 0;
-  }
+  /* Keep preview banner fixed on mobile */
   
   /* Keep breadcrumbs fixed on mobile to prevent double spacing */
 }

package/html/documentation-index.html

@@ -29,7 +29,7 @@
             
             <div class="header-actions">
                 <div class="deployment-info">
-                    <span class="deployment-date" title="Built with doc-builder v1.4.21">Last updated: Jul 21, 2025, 06:12 PM UTC</span>
+                    <span class="deployment-date" title="Built with doc-builder v1.4.23">Last updated: Jul 21, 2025, 07:42 PM UTC</span>
                 </div>
                 
                 
@@ -86,7 +86,9 @@
           <i class="fas fa-chevron-right collapse-icon"></i><i class="fas fa-folder"></i> Guides
         </a>
         <div class="nav-content collapsed" id="nav-guides-1">
-        <a href="/guides/DOCUMENT-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> DOCUMENT STANDARDS</a></div></div>
+        <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/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>
         </aside>
@@ -104,7 +106,9 @@
 ├── documentation-index.md       # This file - documentation map
 ├── claude-workflow-guide.md     # AI workflow guide
 └── guides/                      # How-to guides and standards
-    └── DOCUMENT-STANDARDS.md    # Documentation standards
+    ├── authentication-guide.md  # Authentication setup and usage
+    ├── documentation-standards.md # Documentation standards
+    └── troubleshooting-guide.md # Common issues and solutions
 </code></pre>
 <h2>Documentation Categories</h2>
 <h3>📚 Core Documentation</h3>
@@ -143,10 +147,20 @@
 </thead>
 <tbody><tr>
 <td>Document Standards</td>
-<td><a href="./guides/DOCUMENT-STANDARDS.md">guides/DOCUMENT-STANDARDS.md</a></td>
+<td><a href="./guides/documentation-standards.md">guides/documentation-standards.md</a></td>
 <td>How to write docs for this project</td>
 </tr>
 <tr>
+<td>Authentication Guide</td>
+<td><a href="./guides/authentication-guide.md">guides/authentication-guide.md</a></td>
+<td>Setting up password protection</td>
+</tr>
+<tr>
+<td>Troubleshooting Guide</td>
+<td><a href="./guides/troubleshooting-guide.md">guides/troubleshooting-guide.md</a></td>
+<td>Common issues and solutions</td>
+</tr>
+<tr>
 <td>Claude Workflow</td>
 <td><a href="./claude-workflow-guide.md">claude-workflow-guide.md</a></td>
 <td>Using Claude with doc-builder</td>
@@ -156,9 +170,9 @@
 <ul>
 <li><strong>API Reference</strong> - Detailed API documentation</li>
 <li><strong>Architecture Guide</strong> - System design and components</li>
-<li><strong>Troubleshooting</strong> - Common issues and solutions</li>
 <li><strong>Plugin Development</strong> - Extending doc-builder</li>
 <li><strong>Migration Guide</strong> - Upgrading from older versions</li>
+<li><strong>Performance Guide</strong> - Optimizing large documentation sites</li>
 </ul>
 <h2>Quick Start Guides</h2>
 <h3>For Users</h3>
@@ -228,6 +242,18 @@ Detailed information...
 <td>System</td>
 <td>Initial documentation index</td>
 </tr>
+<tr>
+<td>2025-07-21</td>
+<td>1.1</td>
+<td>System</td>
+<td>Added authentication guide</td>
+</tr>
+<tr>
+<td>2025-07-21</td>
+<td>1.2</td>
+<td>System</td>
+<td>Added troubleshooting guide</td>
+</tr>
 </tbody></table>
 
             </div>