@knowcode/doc-builder 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -5,6 +5,37 @@ 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.2.2] - 2025-07-19
+
+### Fixed
+- Removed accidentally included temp-test directory from npm package
+- Added .npmignore file to prevent test directories from being published
+
+## [1.2.1] - 2025-07-19
+
+### Added
+- **Auto-generated README.md** - System now automatically creates a helpful placeholder README.md when missing
+- Comprehensive placeholder content with getting started guide and documentation standards
+- Clear instructions for users on how to customize their documentation
+- Built-in Mermaid diagram example in generated README
+- Documentation structure recommendations and best practices
+
+### Fixed
+- **Eliminated ugly file listing** on index page when no README exists
+- Improved first-time user experience with welcoming placeholder content
+- Better guidance for documentation creation and organization
+
+### Changed
+- Simplified deployment logic - removed complex HTML file listing generation
+- Build process now checks and creates README.md before scanning files
+- Deploy process simplified since README.html will always exist
+
+### Technical Improvements
+- Added `createPlaceholderReadme()` function to core-builder.js
+- Integrated README generation into main build workflow
+- Enhanced build logging to show when placeholder is generated
+- Exported new function for potential external usage
+
 ## [1.2.0] - 2025-07-19
 
 ### Added (MAJOR FEATURE RELEASE)

package/lib/core-builder.js

@@ -448,9 +448,13 @@ async function buildDocumentation(config) {
   const docsDir = path.join(process.cwd(), config.docsDir);
   const outputDir = path.join(process.cwd(), config.outputDir);
   
+  // Check and create placeholder README.md if missing
+  console.log(chalk.blue('📋 Checking documentation structure...'));
+  const readmeGenerated = await createPlaceholderReadme(docsDir, config);
+  
   console.log(chalk.blue('📄 Scanning for markdown files...'));
   const files = await getAllMarkdownFiles(docsDir);
-  console.log(chalk.green(`✅ Found ${files.length} markdown files`));
+  console.log(chalk.green(`✅ Found ${files.length} markdown files${readmeGenerated ? ' (including auto-generated README)' : ''}`));
   
   console.log(chalk.blue('📝 Processing files...'));
   for (const file of files) {
@@ -489,6 +493,99 @@ async function buildDocumentation(config) {
   console.log(chalk.green('✅ Documentation build complete!'));
 }
 
+// Create placeholder README.md if missing
+async function createPlaceholderReadme(docsDir, config) {
+  const readmePath = path.join(docsDir, 'README.md');
+  
+  // Check if README.md already exists
+  if (fs.existsSync(readmePath)) {
+    return false; // README already exists, no need to create
+  }
+  
+  const siteName = config.siteName || 'Documentation';
+  const currentDate = new Date().toISOString().split('T')[0];
+  
+  const placeholderContent = `# Welcome to ${siteName}
+
+**Generated**: ${currentDate} UTC
+**Status**: Placeholder - Ready for customization
+**Verified**: ❓ (Auto-generated content)
+
+## Overview
+
+This documentation site was built with @knowcode/doc-builder. This is an auto-generated placeholder to help you get started.
+
+## Getting Started
+
+1. **Replace this file**: Edit \`docs/README.md\` with your project's actual documentation
+2. **Add content**: Create additional markdown files in the \`docs/\` directory
+3. **Organize with folders**: Use subfolders to structure your documentation
+4. **Rebuild**: Run \`npx @knowcode/doc-builder build\` to regenerate the site
+
+## Documentation Structure
+
+Your documentation can include:
+
+- **Overview**: Main project description (this file)
+- **Guides**: Step-by-step tutorials
+- **API Reference**: Technical documentation
+- **Examples**: Code samples and usage
+- **Architecture**: System design and technical details
+
+## Next Steps
+
+1. Edit this README.md file with your project information
+2. Create additional markdown files for your content
+3. Organize files into logical folders
+4. Use Mermaid diagrams for visual explanations
+5. Deploy with \`npx @knowcode/doc-builder deploy\`
+
+## Documentation Standards
+
+This project follows structured documentation conventions:
+
+### File Organization
+- Use descriptive filenames with hyphens (e.g., \`user-guide.md\`)
+- Organize related content in folders
+- Include a README.md in each major folder
+
+### Content Format
+- Start each document with metadata (Generated date, Status, Verified status)
+- Use clear headings and consistent structure
+- Include diagrams where helpful to explain concepts
+- Mark information as verified (✅) or speculated (❓)
+
+### Mermaid Diagrams
+Include visual diagrams to explain complex concepts:
+
+\`\`\`mermaid
+graph TD
+    A[Start Documentation] --> B{Have Content?}
+    B -->|Yes| C[Edit README.md]
+    B -->|No| D[Create Content Files]
+    C --> E[Build & Deploy]
+    D --> E
+    E --> F[Share Documentation]
+\`\`\`
+
+## Support
+
+For help with @knowcode/doc-builder:
+- Check the documentation at your package source
+- Use \`npx @knowcode/doc-builder --help\` for CLI options
+- Review the generated configuration guide if available
+`;
+
+  try {
+    await fs.writeFile(readmePath, placeholderContent);
+    console.log(chalk.yellow('📄 Auto-generated placeholder README.md - please customize it!'));
+    return true; // Successfully created placeholder
+  } catch (error) {
+    console.warn(chalk.yellow(`Warning: Could not create placeholder README.md: ${error.message}`));
+    return false;
+  }
+}
+
 // Create login/logout pages
 async function createAuthPages(outputDir, config) {
   // Login page
@@ -570,5 +667,6 @@ async function createAuthPages(outputDir, config) {
 module.exports = {
   buildDocumentation,
   processMarkdownContent,
-  generateHTML
+  generateHTML,
+  createPlaceholderReadme
 };

package/lib/deploy.js

@@ -365,72 +365,29 @@ async function prepareDeployment(config) {
       fs.writeFileSync(indexPath, redirectHtml);
       console.log(chalk.green('✅ Created index.html redirect to README.html'));
     } else {
-      // If no README.html, create a basic index listing all HTML files
-      const htmlFiles = fs.readdirSync(outputDir)
-        .filter(file => file.endsWith('.html') && file !== 'index.html')
-        .sort();
-      
-      if (htmlFiles.length > 0) {
-        const indexHtml = `<!DOCTYPE html>
+      // If no README.html, create a simple redirect to home
+      // This should rarely happen since build process now auto-generates README.md
+      const simpleIndex = `<!DOCTYPE html>
 <html>
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Documentation</title>
-  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0-beta3/css/all.min.css">
+  <meta http-equiv="refresh" content="0; url=./">
+  <title>${config.siteName || 'Documentation'}</title>
   <link rel="stylesheet" href="/css/style.css">
   <link rel="stylesheet" href="/css/notion-style.css">
 </head>
 <body>
-  <div class="navigation">
-    <div class="nav-header">
-      <h2>${config.siteName || 'Documentation'}</h2>
-    </div>
-    <nav>
-      <ul>
-        ${htmlFiles.map(file => {
-          const name = file.replace('.html', '').replace(/-/g, ' ');
-          const capitalizedName = name.split(' ').map(word => 
-            word.charAt(0).toUpperCase() + word.slice(1)
-          ).join(' ');
-          return `<li><a href="${file}"><i class="fas fa-file"></i> ${capitalizedName}</a></li>`;
-        }).join('\n        ')}
-      </ul>
-    </nav>
-  </div>
-  <div class="content">
-    <div class="header">
-      <h1 style="text-align: center; margin: 50px 0;">📚 Documentation</h1>
-    </div>
-    <div class="main-content">
-      <div class="doc-grid" style="display: grid; grid-template-columns: repeat(auto-fill, minmax(300px, 1fr)); gap: 20px; padding: 20px;">
-        ${htmlFiles.map(file => {
-          const name = file.replace('.html', '').replace(/-/g, ' ');
-          const capitalizedName = name.split(' ').map(word => 
-            word.charAt(0).toUpperCase() + word.slice(1)
-          ).join(' ');
-          return `
-        <a href="${file}" class="doc-card" style="display: block; padding: 20px; border: 1px solid #e1e4e8; border-radius: 8px; text-decoration: none; color: inherit; transition: all 0.2s;">
-          <h3 style="margin: 0 0 10px 0; color: #0366d6;"><i class="fas fa-file-alt"></i> ${capitalizedName}</h3>
-          <p style="margin: 0; color: #586069; font-size: 14px;">Click to view this documentation</p>
-        </a>`;
-        }).join('')}
-      </div>
-    </div>
+  <div style="text-align: center; margin-top: 50px; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;">
+    <h1>📚 ${config.siteName || 'Documentation'}</h1>
+    <p>Loading documentation...</p>
+    <p><a href="./" style="color: #0366d6;">Click here if not redirected automatically</a></p>
   </div>
-  <script src="/js/main.js"></script>
-  <style>
-    .doc-card:hover {
-      box-shadow: 0 4px 12px rgba(0,0,0,0.1);
-      transform: translateY(-2px);
-    }
-  </style>
 </body>
 </html>`;
-        fs.writeFileSync(indexPath, indexHtml);
-        console.log(chalk.green('✅ Created index.html with file listing'));
-        console.log(chalk.yellow('📌 Remember to rebuild before deploying to see styling!'));
-      }
+      fs.writeFileSync(indexPath, simpleIndex);
+      console.log(chalk.green('✅ Created index.html redirect'));
+      console.log(chalk.yellow('📌 Note: Consider running build to ensure README.md exists'));
     }
   }
 }

package/package.json

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