zengen 0.1.0

package/src/builder.ts

@@ -0,0 +1,292 @@
+import { BuildOptions, FileInfo, NavigationItem, ZenConfig } from './types';
+import { MarkdownConverter } from './markdown';
+import { TemplateEngine } from './template';
+import { NavigationGenerator } from './navigation';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as chokidar from 'chokidar';
+
+export class ZenBuilder {
+  private markdownConverter: MarkdownConverter;
+  private templateEngine: TemplateEngine;
+  private navigationGenerator: NavigationGenerator;
+  private config: ZenConfig = {};
+
+  constructor(config: ZenConfig = {}) {
+    this.config = config;
+    this.markdownConverter = new MarkdownConverter(config.processors || []);
+    this.templateEngine = new TemplateEngine();
+    this.navigationGenerator = new NavigationGenerator();
+  }
+
+  /**
+   * 构建文档站点
+   */
+  async build(options: BuildOptions): Promise<void> {
+    const startTime = Date.now();
+    const { srcDir, outDir, template, verbose = false } = options;
+
+    if (verbose) {
+      console.log(`🚀 Starting ZEN build...`);
+      console.log(`📁 Source: ${srcDir}`);
+      console.log(`📁 Output: ${outDir}`);
+    }
+
+    // 验证源目录
+    try {
+      await fs.access(srcDir);
+    } catch (error) {
+      throw new Error(`Source directory does not exist: ${srcDir}`);
+    }
+
+    // 确保输出目录存在
+    await fs.mkdir(outDir, { recursive: true });
+
+    // 读取并转换 Markdown 文件
+    if (verbose) console.log(`📄 Reading Markdown files...`);
+    const files = await this.markdownConverter.convertDirectory(srcDir);
+
+    if (files.length === 0) {
+      console.warn(`⚠️ No Markdown files found in ${srcDir}`);
+      return;
+    }
+
+    if (verbose) console.log(`✅ Found ${files.length} Markdown files`);
+
+    // 生成导航
+    if (verbose) console.log(`🗺️ Generating navigation...`);
+    const navigation = this.navigationGenerator.generate(files);
+
+    // 处理每个文件
+    if (verbose) console.log(`⚡ Processing files...`);
+    let processedCount = 0;
+
+    for (const file of files) {
+      try {
+        // 生成模板数据
+        const templateData = this.templateEngine.generateTemplateData(file, navigation);
+
+        // 渲染模板
+        const html = await this.templateEngine.render(templateData, template);
+
+        // 生成输出路径
+        const outputPath = this.templateEngine.getOutputPath(file, outDir);
+
+        // 保存文件
+        await this.templateEngine.saveToFile(html, outputPath);
+
+        processedCount++;
+
+        if (verbose && processedCount % 10 === 0) {
+          console.log(`  Processed ${processedCount}/${files.length} files...`);
+        }
+      } catch (error) {
+        console.error(`❌ Failed to process ${file.relativePath}:`, error);
+      }
+    }
+
+    // 生成站点地图
+    if (verbose) console.log(`🗺️ Generating sitemap...`);
+    await this.generateSitemap(files, outDir);
+
+    // 生成导航 JSON 文件
+    if (verbose) console.log(`📊 Generating navigation data...`);
+    await this.generateNavigationJson(files, outDir);
+
+    // 复制静态资源（如果存在）
+    await this.copyStaticAssets(srcDir, outDir);
+
+    const duration = Date.now() - startTime;
+    if (verbose) {
+      console.log(`🎉 Build completed!`);
+      console.log(`   Files processed: ${processedCount}/${files.length}`);
+      console.log(`   Duration: ${duration}ms`);
+      console.log(`   Output directory: ${outDir}`);
+    } else {
+      console.log(`✅ Built ${processedCount} files to ${outDir} in ${duration}ms`);
+    }
+  }
+
+  /**
+   * 监听文件变化并自动重建
+   */
+  async watch(options: BuildOptions): Promise<void> {
+    const { srcDir, outDir, template, verbose = false } = options;
+
+    console.log(`👀 Watching for changes in ${srcDir}...`);
+    console.log(`Press Ctrl+C to stop watching`);
+
+    // 初始构建
+    await this.build(options);
+
+    // 设置文件监听
+    const watcher = chokidar.watch(srcDir, {
+      ignored: /(^|[\/\\])\../, // 忽略隐藏文件
+      persistent: true,
+      ignoreInitial: true
+    });
+
+    let isBuilding = false;
+    let buildQueue: string[] = [];
+
+    const debouncedBuild = async () => {
+      if (isBuilding) {
+        return;
+      }
+
+      isBuilding = true;
+      const changedFiles = [...buildQueue];
+      buildQueue = [];
+
+      try {
+        if (verbose) {
+          console.log(`\n🔄 Rebuilding due to changes in: ${changedFiles.join(', ')}`);
+        } else {
+          console.log(`\n🔄 Rebuilding...`);
+        }
+
+        await this.build(options);
+        console.log(`✅ Rebuild complete. Watching for changes...`);
+      } catch (error) {
+        console.error(`❌ Rebuild failed:`, error);
+      } finally {
+        isBuilding = false;
+
+        // 如果队列中有新文件，立即处理
+        if (buildQueue.length > 0) {
+          setTimeout(debouncedBuild, 100);
+        }
+      }
+    };
+
+    watcher
+      .on('add', (filePath: string) => {
+        if (filePath.endsWith('.md')) {
+          if (verbose) console.log(`📄 File added: ${filePath}`);
+          buildQueue.push(filePath);
+          setTimeout(debouncedBuild, 300);
+        }
+      })
+      .on('change', (filePath: string) => {
+        if (filePath.endsWith('.md')) {
+          if (verbose) console.log(`📄 File changed: ${filePath}`);
+          buildQueue.push(filePath);
+          setTimeout(debouncedBuild, 300);
+        }
+      })
+      .on('unlink', (filePath: string) => {
+        if (filePath.endsWith('.md')) {
+          if (verbose) console.log(`📄 File removed: ${filePath}`);
+          buildQueue.push(filePath);
+          setTimeout(debouncedBuild, 300);
+        }
+      })
+      .on('error', (error: unknown) => {
+        console.error(`❌ Watcher error:`, error);
+      });
+
+    // 处理退出信号
+    process.on('SIGINT', () => {
+      console.log(`\n👋 Stopping watcher...`);
+      watcher.close();
+      process.exit(0);
+    });
+  }
+
+  /**
+   * 生成站点地图
+   */
+  private async generateSitemap(files: FileInfo[], outDir: string): Promise<void> {
+    try {
+      const sitemapXml = this.navigationGenerator.generateSitemap(files);
+      const sitemapPath = path.join(outDir, 'sitemap.xml');
+      await fs.writeFile(sitemapPath, sitemapXml, 'utf-8');
+    } catch (error) {
+      console.warn(`⚠️ Failed to generate sitemap:`, error);
+    }
+  }
+
+  /**
+   * 生成导航 JSON 文件
+   */
+  private async generateNavigationJson(files: FileInfo[], outDir: string): Promise<void> {
+    try {
+      const navigationJson = this.navigationGenerator.generateJsonNavigation(files);
+      const navPath = path.join(outDir, 'navigation.json');
+      await fs.writeFile(navPath, navigationJson, 'utf-8');
+    } catch (error) {
+      console.warn(`⚠️ Failed to generate navigation JSON:`, error);
+    }
+  }
+
+  /**
+   * 复制静态资源
+   */
+  private async copyStaticAssets(srcDir: string, outDir: string): Promise<void> {
+    const staticDir = path.join(srcDir, 'static');
+
+    try {
+      await fs.access(staticDir);
+
+      // 简单的递归复制
+      async function copyDir(source: string, target: string) {
+        await fs.mkdir(target, { recursive: true });
+        const entries = await fs.readdir(source, { withFileTypes: true });
+
+        for (const entry of entries) {
+          const srcPath = path.join(source, entry.name);
+          const destPath = path.join(target, entry.name);
+
+          if (entry.isDirectory()) {
+            await copyDir(srcPath, destPath);
+          } else {
+            await fs.copyFile(srcPath, destPath);
+          }
+        }
+      }
+
+      await copyDir(staticDir, path.join(outDir, 'static'));
+    } catch (error) {
+      // 静态目录不存在是正常的，忽略错误
+    }
+  }
+
+  /**
+   * 清理输出目录
+   */
+  async clean(outDir: string): Promise<void> {
+    try {
+      await fs.rm(outDir, { recursive: true, force: true });
+      console.log(`🧹 Cleaned output directory: ${outDir}`);
+    } catch (error) {
+      console.error(`❌ Failed to clean output directory:`, error);
+    }
+  }
+
+  /**
+   * 验证配置
+   */
+  validateConfig(config: ZenConfig): string[] {
+    const errors: string[] = [];
+
+    if (config.srcDir && !path.isAbsolute(config.srcDir)) {
+      errors.push('srcDir must be an absolute path');
+    }
+
+    if (config.outDir && !path.isAbsolute(config.outDir)) {
+      errors.push('outDir must be an absolute path');
+    }
+
+    if (config.i18n) {
+      if (!config.i18n.sourceLang) {
+        errors.push('i18n.sourceLang is required');
+      }
+
+      if (!config.i18n.targetLangs || config.i18n.targetLangs.length === 0) {
+        errors.push('i18n.targetLangs must have at least one language');
+      }
+    }
+
+    return errors;
+  }
+}

package/src/cli.ts

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { ZenBuilder } from './builder';
+import { ZenConfig } from './types';
+import * as path from 'path';
+import * as fs from 'fs/promises';
+
+const program = new Command();
+
+program
+  .name('zengen')
+  .description('ZEN - A minimalist Markdown documentation site builder')
+  .version('0.1.0');
+
+// 构建命令
+program
+  .command('build')
+  .description('Build documentation site from Markdown files')
+  .argument('<src-dir>', 'Source directory containing Markdown files')
+  .option('-o, --out <dir>', 'Output directory for generated HTML', 'dist')
+  .option('-t, --template <file>', 'Custom template file')
+  .option('-w, --watch', 'Watch for changes and rebuild automatically')
+  .option('-v, --verbose', 'Show detailed output')
+  .option('-c, --config <file>', 'Configuration file')
+  .option('--clean', 'Clean output directory before building')
+  .action(async (srcDir, options) => {
+    try {
+      // 加载配置文件
+      let config: ZenConfig = {};
+      if (options.config) {
+        try {
+          const configPath = path.resolve(options.config);
+          const configContent = await fs.readFile(configPath, 'utf-8');
+          config = JSON.parse(configContent);
+        } catch (error) {
+          console.error(`❌ Failed to load config file:`, error);
+          process.exit(1);
+        }
+      }
+
+      // 合并命令行参数和配置
+      const buildOptions = {
+        srcDir: path.resolve(srcDir),
+        outDir: path.resolve(options.out),
+        template: options.template ? path.resolve(options.template) : undefined,
+        watch: options.watch,
+        verbose: options.verbose
+      };
+
+      const builder = new ZenBuilder(config);
+
+      // 验证配置
+      const errors = builder.validateConfig(config);
+      if (errors.length > 0) {
+        console.error('❌ Configuration errors:');
+        errors.forEach(error => console.error(`  - ${error}`));
+        process.exit(1);
+      }
+
+      // 清理输出目录
+      if (options.clean) {
+        await builder.clean(buildOptions.outDir);
+      }
+
+      // 构建或监听
+      if (options.watch) {
+        await builder.watch(buildOptions);
+      } else {
+        await builder.build(buildOptions);
+      }
+    } catch (error) {
+      console.error('❌ Build failed:', error);
+      process.exit(1);
+    }
+  });
+
+// 清理命令
+program
+  .command('clean')
+  .description('Clean output directory')
+  .argument('<dir>', 'Directory to clean')
+  .action(async (dir) => {
+    try {
+      const builder = new ZenBuilder();
+      await builder.clean(path.resolve(dir));
+    } catch (error) {
+      console.error('❌ Clean failed:', error);
+      process.exit(1);
+    }
+  });
+
+// 初始化命令
+program
+  .command('init')
+  .description('Initialize a new ZEN project')
+  .option('-d, --dir <directory>', 'Target directory', '.')
+  .action(async (options) => {
+    try {
+      const targetDir = path.resolve(options.dir);
+
+      // 创建目录结构
+      await fs.mkdir(path.join(targetDir, 'docs'), { recursive: true });
+      await fs.mkdir(path.join(targetDir, 'static'), { recursive: true });
+
+      // 创建示例文档
+      const exampleDoc = `# Welcome to ZEN
+
+This is an example documentation page generated by ZEN.
+
+## Getting Started
+
+1. Write your documentation in Markdown format
+2. Run \`zengen build docs --out dist\`
+3. Open the generated HTML files in your browser
+
+## Features
+
+- **Minimal configuration**: Focus on writing, not configuration
+- **Smart navigation**: Automatic navigation generation
+- **Beautiful templates**: Clean, responsive design
+- **Code highlighting**: Syntax highlighting for code blocks
+
+## Example Code
+
+\`\`\`javascript
+// This is a JavaScript example
+console.log('Hello ZEN!');
+\`\`\`
+
+---
+
+*Happy documenting!*`;
+
+      await fs.writeFile(
+        path.join(targetDir, 'docs', 'index.md'),
+        exampleDoc,
+        'utf-8'
+      );
+
+      // 创建配置文件
+      const config = {
+        srcDir: './docs',
+        outDir: './dist',
+        template: undefined,
+        i18n: {
+          sourceLang: 'en-US',
+          targetLangs: ['zh-CN', 'ja-JP']
+        }
+      };
+
+      await fs.writeFile(
+        path.join(targetDir, 'zen.config.json'),
+        JSON.stringify(config, null, 2),
+        'utf-8'
+      );
+
+      // 创建 package.json 脚本（如果不存在）
+      const packageJsonPath = path.join(targetDir, 'package.json');
+      try {
+        const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf-8'));
+
+        if (!packageJson.scripts) {
+          packageJson.scripts = {};
+        }
+
+        packageJson.scripts.build = 'zengen build docs --out dist';
+        packageJson.scripts['build:watch'] = 'zengen build docs --out dist --watch';
+        packageJson.scripts.clean = 'zengen clean dist';
+
+        await fs.writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2), 'utf-8');
+      } catch (error) {
+        // package.json 不存在，创建简单的版本
+        const simplePackageJson = {
+          name: 'zen-docs',
+          version: '1.0.0',
+          scripts: {
+            build: 'zengen build docs --out dist',
+            'build:watch': 'zengen build docs --out dist --watch',
+            clean: 'zengen clean dist'
+          }
+        };
+
+        await fs.writeFile(
+          packageJsonPath,
+          JSON.stringify(simplePackageJson, null, 2),
+          'utf-8'
+        );
+      }
+
+      console.log(`
+🎉 ZEN project initialized successfully!
+
+Next steps:
+1. Add your Markdown files to the 'docs' directory
+2. Run 'npm run build' to generate the site
+3. Run 'npm run build:watch' for development with auto-reload
+
+Project structure:
+${targetDir}/
+├── docs/           # Your documentation files
+│   └── index.md    # Example document
+├── static/         # Static assets (images, CSS, JS)
+├── zen.config.json # Configuration file
+└── package.json    # npm scripts
+
+For more information, visit: https://github.com/yourusername/zen
+      `);
+    } catch (error) {
+      console.error('❌ Initialization failed:', error);
+      process.exit(1);
+    }
+  });
+
+// 信息命令
+program
+  .command('info')
+  .description('Show information about ZEN')
+  .action(() => {
+    console.log(`
+🤖 ZEN - A minimalist Markdown documentation site builder
+
+Version: 0.1.0
+Description: Build beautiful documentation sites from Markdown files
+
+Features:
+  • Minimal configuration required
+  • Smart navigation generation
+  • Beautiful, responsive templates
+  • Code syntax highlighting
+  • Watch mode for development
+  • Sitemap generation
+  • Static asset support
+
+Commands:
+  build     Build documentation site
+  clean     Clean output directory
+  init      Initialize new project
+  info      Show this information
+
+Examples:
+  $ zengen build ./docs --out ./dist
+  $ zengen build ./docs --out ./dist --watch
+  $ zengen init --dir ./my-docs
+  $ zengen clean ./dist
+
+For more help, run: zengen --help
+    `);
+  });
+
+// 默认命令（兼容旧格式）
+program
+  .argument('[src-dir]', 'Source directory')
+  .option('-o, --out <dir>', 'Output directory')
+  .option('-t, --template <file>', 'Custom template file')
+  .option('-w, --watch', 'Watch for changes')
+  .option('-v, --verbose', 'Show detailed output')
+  .action(async (srcDir, options) => {
+    if (!srcDir) {
+      program.help();
+      return;
+    }
+
+    try {
+      const builder = new ZenBuilder();
+
+      const buildOptions = {
+        srcDir: path.resolve(srcDir),
+        outDir: path.resolve(options.out || 'dist'),
+        template: options.template ? path.resolve(options.template) : undefined,
+        watch: options.watch,
+        verbose: options.verbose
+      };
+
+      if (options.watch) {
+        await builder.watch(buildOptions);
+      } else {
+        await builder.build(buildOptions);
+      }
+    } catch (error) {
+      console.error('❌ Build failed:', error);
+      process.exit(1);
+    }
+  });
+
+// 错误处理
+program.showHelpAfterError();
+program.showSuggestionAfterError();
+
+// 解析命令行参数
+program.parse(process.argv);
+
+// 如果没有参数，显示帮助
+if (process.argv.length <= 2) {
+  program.help();
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+export { ZenBuilder } from './builder';
+export { MarkdownConverter } from './markdown';
+export { TemplateEngine } from './template';
+export { NavigationGenerator } from './navigation';
+export type {
+  BuildOptions,
+  FileInfo,
+  NavigationItem,
+  TemplateData,
+  MarkdownProcessor,
+  ZenConfig
+} from './types';
+
+/**
+ * ZEN 文档构建工具
+ *
+ * 一个极简主义的 Markdown 文档站点生成器
+ *
+ * @example
+ * ```typescript
+ * import { ZenBuilder } from 'zengen';
+ *
+ * const builder = new ZenBuilder();
+ * await builder.build({
+ *   srcDir: './docs',
+ *   outDir: './dist'
+ * });
+ * ```
+ */
+import { ZenBuilder } from './builder';
+import { MarkdownConverter } from './markdown';
+import { TemplateEngine } from './template';
+import { NavigationGenerator } from './navigation';
+
+export default {
+  Builder: ZenBuilder,
+  MarkdownConverter: MarkdownConverter,
+  TemplateEngine: TemplateEngine,
+  NavigationGenerator: NavigationGenerator
+};