@knowcode/doc-builder 1.2.0 → 1.2.1

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.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.1",
   "description": "Reusable documentation builder for markdown-based sites with Vercel deployment support",
   "main": "index.js",
   "bin": {

package/temp-test/docs/README.md

@@ -0,0 +1,69 @@
+# Welcome to Documentation
+
+**Generated**: 2025-07-19 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

package/temp-test/docs/test-file.md

@@ -0,0 +1 @@
+# Test File

package/temp-test/html/README.html

@@ -0,0 +1,164 @@
+<!DOCTYPE html>
+<html lang="en">
+<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>Welcome to Documentation - Documentation</title>
+    
+    <!-- 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">
+    
+    <!-- Icons -->
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css">
+    
+    <!-- Mermaid -->
+    <script src="https://cdn.jsdelivr.net/npm/mermaid@10.6.1/dist/mermaid.min.js"></script>
+    
+    <!-- Styles -->
+    <link rel="stylesheet" href="/css/notion-style.css">
+    <link rel="stylesheet" href="/css/style.css">
+    
+    <!-- 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>">
+</head>
+<body>
+    <!-- Header -->
+    <header class="header">
+        <div class="header-content">
+            <a href="/index.html" class="logo">Documentation</a>
+            
+            <div class="header-actions">
+                <div class="deployment-info">
+                    <span class="deployment-date">Last updated: Jul 19, 2025, 11:59 AM UTC</span>
+                </div>
+                
+                
+                
+                <button id="theme-toggle" class="theme-toggle" aria-label="Toggle theme">
+                    <i class="fas fa-moon"></i>
+                </button>
+                
+                <button id="menu-toggle" class="menu-toggle" aria-label="Toggle menu">
+                    <i class="fas fa-bars"></i>
+                </button>
+            </div>
+        </div>
+    </header>
+    
+    <!-- Preview Banner -->
+    <div id="preview-banner" class="preview-banner">
+        <div class="banner-content">
+            <i class="fas fa-exclamation-triangle banner-icon"></i>
+            <span class="banner-text">This documentation is a preview version - some content may be incomplete</span>
+            <button id="dismiss-banner" class="banner-dismiss" aria-label="Dismiss banner">
+                <i class="fas fa-times"></i>
+            </button>
+        </div>
+    </div>
+    
+    <!-- Breadcrumbs -->
+    <nav class="breadcrumbs" id="breadcrumbs">
+        <!-- Breadcrumbs will be generated by JavaScript -->
+    </nav>
+    
+    <!-- Main Content -->
+    <div class="main-wrapper">
+        <!-- Sidebar -->
+        <aside class="sidebar">
+            <div class="sidebar-header">
+                <div class="filter-box">
+                    <input type="text" placeholder="Filter items..." class="filter-input" id="nav-filter">
+                    <i class="fas fa-search filter-icon"></i>
+                </div>
+            </div>
+            <nav class="navigation">
+                
+      <div class="nav-section" data-level="0">
+        <a class="nav-title expanded" href="/README.html"  >
+          <i class="fas fa-home"></i> Documentation
+        </a>
+        <div class="nav-content" >
+        <a href="/README.html" class="nav-item active"><i class="fas fa-file-alt"></i> Overview</a>
+        <a href="/test-file.html" class="nav-item"><i class="fas fa-file-alt"></i> Test File</a></div></div>
+            </nav>
+            <div class="resize-handle"></div>
+        </aside>
+        
+        <!-- Content Area -->
+        <main class="content">
+            <div class="content-inner">
+                <h1>Welcome to Documentation</h1>
+<p><strong>Generated</strong>: 2025-07-19 UTC<br><strong>Status</strong>: Placeholder - Ready for customization<br><strong>Verified</strong>: ❓ (Auto-generated content)</p>
+<h2>Overview</h2>
+<p>This documentation site was built with @knowcode/doc-builder. This is an auto-generated placeholder to help you get started.</p>
+<h2>Getting Started</h2>
+<ol>
+<li><strong>Replace this file</strong>: Edit <code>docs/README.md</code> with your project&#39;s actual documentation</li>
+<li><strong>Add content</strong>: Create additional markdown files in the <code>docs/</code> directory</li>
+<li><strong>Organize with folders</strong>: Use subfolders to structure your documentation</li>
+<li><strong>Rebuild</strong>: Run <code>npx @knowcode/doc-builder build</code> to regenerate the site</li>
+</ol>
+<h2>Documentation Structure</h2>
+<p>Your documentation can include:</p>
+<ul>
+<li><strong>Overview</strong>: Main project description (this file)</li>
+<li><strong>Guides</strong>: Step-by-step tutorials</li>
+<li><strong>API Reference</strong>: Technical documentation</li>
+<li><strong>Examples</strong>: Code samples and usage</li>
+<li><strong>Architecture</strong>: System design and technical details</li>
+</ul>
+<h2>Next Steps</h2>
+<ol>
+<li>Edit this README.md file with your project information</li>
+<li>Create additional markdown files for your content</li>
+<li>Organize files into logical folders</li>
+<li>Use Mermaid diagrams for visual explanations</li>
+<li>Deploy with <code>npx @knowcode/doc-builder deploy</code></li>
+</ol>
+<h2>Documentation Standards</h2>
+<p>This project follows structured documentation conventions:</p>
+<h3>File Organization</h3>
+<ul>
+<li>Use descriptive filenames with hyphens (e.g., <code>user-guide.md</code>)</li>
+<li>Organize related content in folders</li>
+<li>Include a README.md in each major folder</li>
+</ul>
+<h3>Content Format</h3>
+<ul>
+<li>Start each document with metadata (Generated date, Status, Verified status)</li>
+<li>Use clear headings and consistent structure</li>
+<li>Include diagrams where helpful to explain concepts</li>
+<li>Mark information as verified (✅) or speculated (❓)</li>
+</ul>
+<h3>Mermaid Diagrams</h3>
+<p>Include visual diagrams to explain complex concepts:</p>
+<div class="mermaid-wrapper">
+      <div class="mermaid-title">Diagram</div>
+      <div class="mermaid">graph TD
+    A[Start Documentation] --&gt; B{Have Content?}
+    B --&gt;|Yes| C[Edit README.md]
+    B --&gt;|No| D[Create Content Files]
+    C --&gt; E[Build &amp; Deploy]
+    D --&gt; E
+    E --&gt; F[Share Documentation]
+</div>
+    </div>
+
+<h2>Support</h2>
+<p>For help with @knowcode/doc-builder:</p>
+<ul>
+<li>Check the documentation at your package source</li>
+<li>Use <code>npx @knowcode/doc-builder --help</code> for CLI options</li>
+<li>Review the generated configuration guide if available</li>
+</ul>
+
+            </div>
+        </main>
+    </div>
+    
+    <!-- Scripts -->
+    <script src="/js/main.js"></script>
+    
+</body>
+</html>