@knowcode/doc-builder 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+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.0.1] - 2025-01-19
+
+### Fixed
+- Made package completely self-contained - no longer requires cybersolstice project
+- Embedded full build logic into the package
+- Fixed "Build script not found" error when running in other projects
+
+## [1.0.0] - 2025-01-19
+
+### Added
+- Initial release of @knowcode/doc-builder
+- Zero-configuration documentation builder
+- Markdown to HTML conversion with Notion-inspired theme
+- Automatic navigation generation from folder structure
+- Mermaid diagram support with title extraction
+- Syntax highlighting for code blocks
+- Dark mode support
+- Optional authentication system
+- Automatic changelog generation
+- Live reload development server
+- One-command Vercel deployment
+- CLI with build, dev, deploy, and init commands
+- Example documentation generator
+- Cybersolstice preset for backward compatibility
+- Programmatic API for Node.js integration
+
+### Features
+- Works immediately with `npx @knowcode/doc-builder`
+- No installation or configuration required
+- Self-contained package with all dependencies
+- Intelligent defaults for common use cases
+- Full customization available via config file
+
+### Technical
+- Built on marked for markdown parsing
+- Commander.js for CLI framework
+- Supports Node.js 14+
+- CommonJS module system for compatibility
+
+## Future Releases
+
+### [1.1.0] - Planned
+- Plugin system for extensibility
+- Custom theme support
+- Multiple language support
+- Search functionality
+- PDF export
+
+### [2.0.0] - Planned
+- Full refactor of build system
+- ESM modules support
+- TypeScript rewrite
+- Performance improvements

package/lib/builder.js

@@ -1,10 +1,11 @@
 const fs = require('fs-extra');
 const path = require('path');
 const chalk = require('chalk');
+const { buildDocumentation } = require('./core-builder');
 
 /**
  * Main build function
- * This wraps the existing build.js functionality
+ * Now fully self-contained!
  */
 async function build(config) {
   console.log(chalk.blue(`\n🚀 Building ${config.siteName}...\n`));
@@ -14,65 +15,17 @@ async function build(config) {
     throw new Error('Invalid configuration provided to build function');
   }
   
-  // For now, we'll use the existing build.js file
-  // In a future refactor, we'll move all the logic here
-  const buildScriptPath = path.join(__dirname, '../../../html/build.js');
-  
-  if (!fs.existsSync(buildScriptPath)) {
-    throw new Error('Build script not found. This package must be run from the cybersolstice project.');
-  }
-  
-  // Set environment variables for the build script
-  process.env.DOC_BUILDER_CONFIG = JSON.stringify(config);
-  
-  // Import and run the existing build
-  const buildModule = require(buildScriptPath);
-  
-  // Run the build - it doesn't take parameters, config is passed via env
-  if (typeof buildModule.build === 'function') {
-    await buildModule.build();
-  } else {
-    // If it's not a function, it might be auto-executing
-    // Just requiring it should run it
+  try {
+    // Use the self-contained builder
+    await buildDocumentation(config);
+    console.log(chalk.green('\n✨ Build complete!\n'));
+  } catch (error) {
+    console.error(chalk.red('\n❌ Build failed:'), error.message);
+    throw error;
   }
-  
-  // Copy assets to output directory
-  await copyAssets(config);
-  
-  console.log(chalk.green('\n✨ Build complete!\n'));
 }
 
-/**
- * Copy package assets to output directory
- */
-async function copyAssets(config) {
-  const outputDir = path.join(process.cwd(), config.outputDir);
-  const assetsDir = path.join(__dirname, '../assets');
-  
-  // Ensure output directory exists
-  await fs.ensureDir(outputDir);
-  
-  // Copy CSS
-  const cssSource = path.join(assetsDir, 'css');
-  const cssDest = path.join(outputDir, 'css');
-  if (fs.existsSync(cssSource)) {
-    await fs.copy(cssSource, cssDest, { overwrite: true });
-  }
-  
-  // Copy JS
-  const jsSource = path.join(assetsDir, 'js');
-  const jsDest = path.join(outputDir, 'js');
-  if (fs.existsSync(jsSource)) {
-    await fs.copy(jsSource, jsDest, { overwrite: true });
-  }
-  
-  // Copy auth.js to root
-  const authSource = path.join(assetsDir, 'js', 'auth.js');
-  const authDest = path.join(outputDir, 'auth.js');
-  if (fs.existsSync(authSource)) {
-    await fs.copy(authSource, authDest, { overwrite: true });
-  }
-}
+// Asset copying is now handled in core-builder.js
 
 module.exports = {
   build

package/lib/core-builder.js

@@ -0,0 +1,399 @@
+const fs = require('fs-extra');
+const path = require('path');
+const marked = require('marked');
+const chalk = require('chalk');
+
+// Configure marked options
+marked.setOptions({
+  highlight: function(code, lang) {
+    return `<code class="language-${lang}">${escapeHtml(code)}</code>`;
+  },
+  breaks: true,
+  gfm: true
+});
+
+// Helper function to escape HTML
+function escapeHtml(text) {
+  const map = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#039;'
+  };
+  return text.replace(/[&<>"']/g, m => map[m]);
+}
+
+// Process markdown content
+function processMarkdownContent(content) {
+  // Convert mermaid code blocks to mermaid divs with titles
+  content = content.replace(/```mermaid\n([\s\S]*?)```/g, (match, mermaidContent) => {
+    // Try to extract title from mermaid content
+    let title = 'Diagram';
+    
+    // Look for title in various mermaid formats
+    const titlePatterns = [
+      /title\s+([^\n]+)/i,                    // gantt charts: title My Title
+      /graph\s+\w+\[["']([^"']+)["']\]/,     // graph TD["My Title"]
+      /flowchart\s+\w+\[["']([^"']+)["']\]/, // flowchart TD["My Title"]
+      /---\s*title:\s*([^\n]+)\s*---/,       // frontmatter style
+    ];
+    
+    for (const pattern of titlePatterns) {
+      const match = mermaidContent.match(pattern);
+      if (match) {
+        title = match[1].trim();
+        break;
+      }
+    }
+    
+    return `<div class="mermaid-wrapper">
+      <div class="mermaid-title">${escapeHtml(title)}</div>
+      <div class="mermaid">${escapeHtml(mermaidContent)}</div>
+    </div>`;
+  });
+  
+  return marked.parse(content);
+}
+
+// Generate HTML from template
+function generateHTML(title, content, navigation, currentPath = '', config = {}) {
+  const depth = currentPath.split('/').filter(p => p).length;
+  const relativePath = depth > 0 ? '../'.repeat(depth) : './';
+  
+  const siteName = config.siteName || 'Documentation';
+  const siteDescription = config.siteDescription || 'Documentation site';
+  
+  return `<!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="${siteDescription}">
+    <title>${title} - ${siteName}</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="${relativePath}css/notion-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="${relativePath}index.html" class="logo">${siteName}</a>
+            
+            <div class="header-actions">
+                <div class="deployment-info">
+                    <span class="deployment-date">Last updated: ${new Date().toLocaleDateString('en-US', { 
+                        year: 'numeric', 
+                        month: 'short', 
+                        day: 'numeric',
+                        hour: '2-digit',
+                        minute: '2-digit',
+                        timeZone: 'UTC'
+                    })} UTC</span>
+                </div>
+                
+                ${config.features?.authentication ? `
+                <a href="${relativePath}logout.html" class="logout-btn" title="Logout">
+                    <i class="fas fa-sign-out-alt"></i>
+                </a>
+                ` : ''}
+                
+                <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>
+    
+    <div class="container">
+        <!-- Navigation -->
+        <nav id="navigation" class="navigation">
+            <div class="nav-header">
+                <h3>${siteName}</h3>
+            </div>
+            ${navigation}
+        </nav>
+        
+        <!-- Main Content -->
+        <main class="content">
+            ${content}
+        </main>
+    </div>
+    
+    <!-- Scripts -->
+    <script src="${relativePath}js/main.js"></script>
+    ${config.features?.authentication ? `<script src="${relativePath}js/auth.js"></script>` : ''}
+</body>
+</html>`;
+}
+
+// Build navigation structure
+function buildNavigationStructure(files, currentFile) {
+  const tree = { files: [], folders: {} };
+  
+  files.forEach(file => {
+    const parts = file.urlPath.split('/');
+    let current = tree;
+    
+    // Navigate/create folder structure
+    for (let i = 0; i < parts.length - 1; i++) {
+      const folder = parts[i];
+      if (!current.folders[folder]) {
+        current.folders[folder] = { files: [], folders: {} };
+      }
+      current = current.folders[folder];
+    }
+    
+    // Add file to current folder
+    current.files.push(file);
+  });
+  
+  // Generate HTML
+  const generateNavHTML = (node, path = '') => {
+    let html = '';
+    
+    // Add files
+    node.files.forEach(file => {
+      const isActive = file.urlPath === currentFile;
+      const href = file.urlPath.replace(/\\/g, '/');
+      html += `<li class="${isActive ? 'active' : ''}">
+        <a href="${href}" class="nav-link ${isActive ? 'active' : ''}">
+          ${file.displayName}
+        </a>
+      </li>`;
+    });
+    
+    // Add folders
+    Object.entries(node.folders).forEach(([folderName, folderNode]) => {
+      const folderPath = path ? `${path}/${folderName}` : folderName;
+      const hasActiveChild = checkActiveChild(folderNode, currentFile);
+      
+      html += `<li class="nav-folder ${hasActiveChild ? 'active' : ''}">
+        <button class="nav-folder-toggle ${hasActiveChild ? 'active' : ''}" data-folder="${folderPath}">
+          <i class="fas fa-chevron-${hasActiveChild ? 'down' : 'right'}"></i>
+          ${folderName}
+        </button>
+        <ul class="nav-folder-content ${hasActiveChild ? 'active' : ''}">
+          ${generateNavHTML(folderNode, folderPath)}
+        </ul>
+      </li>`;
+    });
+    
+    return html;
+  };
+  
+  const checkActiveChild = (node, currentFile) => {
+    // Check files
+    if (node.files.some(f => f.urlPath === currentFile)) return true;
+    
+    // Check folders recursively
+    return Object.values(node.folders).some(folder => checkActiveChild(folder, currentFile));
+  };
+  
+  return `<ul class="nav-list">${generateNavHTML(tree)}</ul>`;
+}
+
+// Process single markdown file
+async function processMarkdownFile(filePath, outputPath, allFiles, config) {
+  const content = await fs.readFile(filePath, 'utf-8');
+  const fileName = path.basename(filePath, '.md');
+  const relativePath = path.relative(config.docsDir, filePath);
+  const urlPath = relativePath.replace(/\.md$/, '.html').replace(/\\/g, '/');
+  
+  // Extract title from content
+  const titleMatch = content.match(/^#\s+(.+)$/m);
+  const title = titleMatch ? titleMatch[1] : fileName;
+  
+  // Process content
+  const htmlContent = processMarkdownContent(content);
+  
+  // Build navigation
+  const navigation = buildNavigationStructure(allFiles, urlPath);
+  
+  // Generate full HTML
+  const html = generateHTML(title, htmlContent, navigation, urlPath, config);
+  
+  // Write file
+  await fs.ensureDir(path.dirname(outputPath));
+  await fs.writeFile(outputPath, html);
+  
+  return { title, urlPath };
+}
+
+// Get all markdown files
+async function getAllMarkdownFiles(dir, baseDir = dir) {
+  const files = [];
+  const items = await fs.readdir(dir);
+  
+  for (const item of items) {
+    const fullPath = path.join(dir, item);
+    const stat = await fs.stat(fullPath);
+    
+    if (stat.isDirectory() && !item.startsWith('.')) {
+      const subFiles = await getAllMarkdownFiles(fullPath, baseDir);
+      files.push(...subFiles);
+    } else if (item.endsWith('.md')) {
+      const relativePath = path.relative(baseDir, fullPath);
+      const urlPath = relativePath.replace(/\.md$/, '.html').replace(/\\/g, '/');
+      const displayName = path.basename(item, '.md')
+        .replace(/[-_]/g, ' ')
+        .replace(/\b\w/g, l => l.toUpperCase());
+      
+      files.push({
+        path: fullPath,
+        relativePath,
+        urlPath,
+        displayName
+      });
+    }
+  }
+  
+  return files;
+}
+
+// Main build function
+async function buildDocumentation(config) {
+  const docsDir = path.join(process.cwd(), config.docsDir);
+  const outputDir = path.join(process.cwd(), config.outputDir);
+  
+  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.blue('📝 Processing files...'));
+  for (const file of files) {
+    const outputPath = path.join(outputDir, file.urlPath);
+    await processMarkdownFile(file.path, outputPath, files, config);
+    console.log(chalk.green(`✅ Generated: ${outputPath}`));
+  }
+  
+  // Copy assets
+  const assetsDir = path.join(__dirname, '../assets');
+  const cssSource = path.join(assetsDir, 'css');
+  const jsSource = path.join(assetsDir, 'js');
+  
+  if (fs.existsSync(cssSource)) {
+    await fs.copy(cssSource, path.join(outputDir, 'css'), { overwrite: true });
+  }
+  
+  if (fs.existsSync(jsSource)) {
+    await fs.copy(jsSource, path.join(outputDir, 'js'), { overwrite: true });
+    
+    // Copy auth.js to root if authentication is enabled
+    if (config.features?.authentication) {
+      const authSource = path.join(jsSource, 'auth.js');
+      const authDest = path.join(outputDir, 'auth.js');
+      if (fs.existsSync(authSource)) {
+        await fs.copy(authSource, authDest, { overwrite: true });
+      }
+    }
+  }
+  
+  // Create auth pages if needed
+  if (config.features?.authentication) {
+    await createAuthPages(outputDir, config);
+  }
+  
+  console.log(chalk.green('✅ Documentation build complete!'));
+}
+
+// Create login/logout pages
+async function createAuthPages(outputDir, config) {
+  // Login page
+  const loginHTML = `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Login - ${config.siteName}</title>
+    <link rel="stylesheet" href="css/notion-style.css">
+</head>
+<body>
+    <div class="auth-container">
+        <div class="auth-box">
+            <h1>Login to ${config.siteName}</h1>
+            <form id="login-form">
+                <div class="form-group">
+                    <label for="username">Username</label>
+                    <input type="text" id="username" name="username" required>
+                </div>
+                <div class="form-group">
+                    <label for="password">Password</label>
+                    <input type="password" id="password" name="password" required>
+                </div>
+                <button type="submit" class="auth-button">Login</button>
+            </form>
+            <div id="error-message" class="error-message"></div>
+        </div>
+    </div>
+    <script>
+        document.getElementById('login-form').addEventListener('submit', function(e) {
+            e.preventDefault();
+            const username = document.getElementById('username').value;
+            const password = document.getElementById('password').value;
+            
+            // Validate credentials
+            if (username === '${config.auth.username}' && password === '${config.auth.password}') {
+                // Set auth cookie
+                const token = btoa(username + ':' + password);
+                document.cookie = 'juno-auth=' + token + '; path=/';
+                
+                // Redirect
+                const params = new URLSearchParams(window.location.search);
+                const redirect = params.get('redirect') || '/';
+                window.location.href = redirect;
+            } else {
+                document.getElementById('error-message').textContent = 'Invalid username or password';
+            }
+        });
+    </script>
+</body>
+</html>`;
+
+  await fs.writeFile(path.join(outputDir, 'login.html'), loginHTML);
+
+  // Logout page
+  const logoutHTML = `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Logged Out - ${config.siteName}</title>
+    <link rel="stylesheet" href="css/notion-style.css">
+</head>
+<body>
+    <div class="auth-container">
+        <div class="auth-box">
+            <h1>You have been logged out</h1>
+            <p>Thank you for using ${config.siteName}.</p>
+            <a href="login.html" class="auth-button">Login Again</a>
+        </div>
+    </div>
+</body>
+</html>`;
+
+  await fs.writeFile(path.join(outputDir, 'logout.html'), logoutHTML);
+}
+
+module.exports = {
+  buildDocumentation,
+  processMarkdownContent,
+  generateHTML
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowcode/doc-builder",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Reusable documentation builder for markdown-based sites with Vercel deployment support",
   "main": "index.js",
   "bin": {
@@ -32,4 +32,4 @@
   "engines": {
     "node": ">=14.0.0"
   }
-}
+}