zengen 0.1.0

package/README.md

@@ -0,0 +1,138 @@
+# ZEN - 简洁的 Markdown 文档站点构建工具
+
+> 📖 **阅读提示**: 本 README 采用中英文分离排版。中文版本在上方，英文版本在下方分隔线之后。
+
+## 项目初衷
+
+### 回归内容
+我喜欢沉思，但不想要配置复杂的构建工具，折腾复杂的文档配置，不喜欢复杂的结构。
+
+### 回归母语
+生命苦短，我用 AI 翻译。与世界保持连接。
+
+## 基本功能
+
+1. **静态站点生成**
+   - 将任意一个包含 Markdown 的文件夹构建成一个静态 HTML 站点
+
+2. **智能导航**
+   - 生成站点地图和导航，不需要保持原始的 Markdown 源文件的目录结构
+
+3. **增量 i18n 翻译**
+   - 使用 LLM 进行增量 i18n 翻译，让用户使用母语编写 Markdown，但是用户可以是多语言的
+
+## 设计理念
+
+- **极简主义**: 最少的配置，最大的灵活性
+- **内容优先**: 专注于写作，而不是工具配置
+- **AI 赋能**: 利用 AI 处理翻译和内容组织
+- **跨语言**: 支持多语言内容创作和展示
+
+## 快速开始
+
+### 安装
+
+```bash
+npm install -g zengen
+```
+
+或者作为项目依赖安装：
+
+```bash
+npm install zengen
+```
+
+### 使用
+
+1. **初始化项目**：
+```bash
+zengen init
+```
+
+2. **构建文档站点**：
+```bash
+zengen build ./docs
+```
+
+3. **实时预览（监听文件变化）**：
+```bash
+zengen build ./docs --watch
+```
+
+4. **查看帮助**：
+```bash
+zengen --help
+```
+
+---
+
+# ZEN - A minimalist Markdown documentation site builder
+
+> 📖 **Reading Note**: This README uses separated Chinese/English layout. Chinese version is above, English version is below the separator line.
+
+## Project Philosophy
+
+### Return to Content
+I enjoy contemplation, but don't want complex build tools, complicated documentation configurations, or intricate structures.
+
+### Return to Native Language
+Life is short, I use AI translation. Stay connected with the world.
+
+## Core Features
+
+1. **Static Site Generation**
+   - Build any folder containing Markdown files into a static HTML site
+
+2. **Smart Navigation**
+   - Generate sitemap and navigation without preserving the original Markdown directory structure
+
+3. **Incremental i18n Translation**
+   - Use LLM for incremental i18n translation, allowing users to write Markdown in their native language while supporting multilingual audiences
+
+## Design Principles
+
+- **Minimalism**: Minimum configuration, maximum flexibility
+- **Content First**: Focus on writing, not tool configuration
+- **AI Empowered**: Leverage AI for translation and content organization
+- **Cross-Language**: Support multilingual content creation and presentation
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install -g zengen
+```
+
+Or install as a project dependency:
+
+```bash
+npm install zengen
+```
+
+### Usage
+
+1. **Initialize a project**:
+```bash
+zengen init
+```
+
+2. **Build documentation site**:
+```bash
+zengen build ./docs
+```
+
+3. **Live preview (watch for changes)**:
+```bash
+zengen build ./docs --watch
+```
+
+4. **View help**:
+```bash
+zengen --help
+```
+
+---
+
+**ZEN** - 让文档回归本质，让写作回归宁静。
+**ZEN** - Return documentation to its essence, return writing to tranquility.

package/demo/src/api.md

@@ -0,0 +1,92 @@
+# API 文档
+
+ZEN 提供了简单易用的 API 来构建文档站点。
+
+## 核心 API
+
+### `build(options: BuildOptions): Promise<void>`
+
+构建文档站点的主要函数。
+
+**参数:**
+- `options.srcDir`: 源 Markdown 文件目录
+- `options.outDir`: 输出 HTML 文件目录
+- `options.template?`: 自定义模板路径（可选）
+- `options.i18n?`: 多语言配置（可选）
+
+**示例:**
+```typescript
+import { build } from 'zengen';
+
+await build({
+  srcDir: './docs',
+  outDir: './dist',
+  template: './custom-template.html'
+});
+```
+
+### `generateNavigation(files: string[]): NavigationItem[]`
+
+生成导航结构。
+
+**参数:**
+- `files`: Markdown 文件路径数组
+
+**返回:**
+导航项数组，包含标题、路径和子项。
+
+## 配置选项
+
+### BuildOptions 接口
+
+```typescript
+interface BuildOptions {
+  srcDir: string;
+  outDir: string;
+  template?: string;
+  i18n?: {
+    sourceLang: string;
+    targetLangs: string[];
+    apiKey?: string;
+  };
+  includePattern?: string;
+  excludePattern?: string;
+}
+```
+
+## 插件系统
+
+ZEN 支持插件扩展功能：
+
+### 自定义处理器
+
+```typescript
+interface MarkdownProcessor {
+  beforeParse?(content: string): string;
+  afterParse?(html: string, metadata: any): string;
+}
+
+// 注册处理器
+zen.registerProcessor('my-processor', {
+  beforeParse(content) {
+    // 预处理 Markdown
+    return content;
+  }
+});
+```
+
+### 自定义模板引擎
+
+```typescript
+interface TemplateEngine {
+  render(template: string, data: any): string;
+}
+
+// 注册模板引擎
+zen.registerTemplateEngine('handlebars', {
+  render(template, data) {
+    // 渲染模板
+    return rendered;
+  }
+});
+```

package/demo/src/best-practices.md

@@ -0,0 +1,194 @@
+# 最佳实践
+
+本文档介绍使用 ZEN 构建文档站点的最佳实践。
+
+## 文件组织
+
+### 推荐的文件结构
+
+```
+project/
+├── docs/                    # 文档源文件
+│   ├── getting-started.md   # 入门指南
+│   ├── api/                 # API 文档目录
+│   │   ├── overview.md
+│   │   ├── core-api.md
+│   │   └── plugins.md
+│   ├── guides/              # 指南目录
+│   │   ├── installation.md
+│   │   └── configuration.md
+│   └── resources/           # 资源文件
+│       └── images/
+├── zen.config.js            # ZEN 配置文件
+└── package.json
+```
+
+### 命名约定
+
+- 使用小写字母和连字符：`getting-started.md`
+- 避免特殊字符和空格
+- 主要页面使用简短名称：`index.md`, `api.md`
+- 分类页面使用目录组织
+
+## 写作规范
+
+### Markdown 语法
+
+**推荐:**
+```markdown
+# 一级标题
+## 二级标题
+### 三级标题
+
+使用 **粗体** 和 *斜体* 强调重要内容。
+
+- 列表项 1
+- 列表项 2
+  - 子列表项
+
+1. 有序列表项 1
+2. 有序列表项 2
+
+> 引用重要的说明或提示。
+
+`行内代码` 用于技术术语。
+
+```javascript
+// 代码块示例
+console.log("Hello ZEN!");
+```
+```
+
+**避免:**
+- 过多的标题层级（超过 4 级）
+- 复杂的表格（考虑使用简单列表替代）
+- 过长的行（建议 80-100 字符换行）
+
+### 元数据使用
+
+在每个 Markdown 文件顶部添加 frontmatter：
+
+```yaml
+---
+title: 页面标题
+description: 简洁的页面描述
+keywords: [关键词1, 关键词2]
+author: 作者名
+date: 2024-01-01
+last_modified: 2024-01-15
+---
+```
+
+## 多语言管理
+
+### 翻译策略
+
+1. **主语言优先**: 先用母语完整编写文档
+2. **增量翻译**: 每次更新后只翻译修改部分
+3. **术语一致**: 建立术语表保持翻译一致性
+4. **人工校对**: AI 翻译后建议人工校对
+
+### 翻译文件管理
+
+```
+docs/
+├── index.zh-CN.md      # 中文源文件
+├── index.en-US.md      # 英文翻译
+├── api/
+│   ├── overview.zh-CN.md
+│   └── overview.en-US.md
+└── glossary.json       # 术语表
+```
+
+## 性能优化
+
+### 构建优化
+
+1. **增量构建**: 使用 `--watch` 模式开发
+2. **缓存利用**: ZEN 会自动缓存处理结果
+3. **并行处理**: 多核 CPU 自动并行处理文件
+
+### 输出优化
+
+1. **压缩 HTML**: 生产环境启用 HTML 压缩
+2. **资源优化**: 图片压缩和 CSS/JS 合并
+3. **CDN 部署**: 静态文件使用 CDN 加速
+
+## 部署策略
+
+### 本地预览
+
+```bash
+# 开发时监听变化
+zengen ./docs --out ./dist --watch
+
+# 启动本地服务器
+npx serve ./dist
+```
+
+### CI/CD 集成
+
+```yaml
+# GitHub Actions 示例
+name: Build and Deploy
+on:
+  push:
+    branches: [main]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+      - run: npm ci
+      - run: npx zengen ./docs --out ./dist
+      - uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./dist
+```
+
+### 云部署
+
+- **Vercel**: 自动部署静态站点
+- **Netlify**: 支持表单处理和重定向
+- **GitHub Pages**: 免费托管文档
+- **AWS S3**: 企业级静态托管
+
+## 维护建议
+
+### 定期更新
+
+1. **内容审核**: 每月检查文档准确性
+2. **链接检查**: 定期检查死链
+3. **性能监控**: 监控页面加载速度
+4. **用户反馈**: 收集用户反馈改进文档
+
+### 版本控制
+
+1. **文档版本化**: 与软件版本同步
+2. **变更日志**: 记录文档更新历史
+3. **回滚机制**: 支持快速回滚到旧版本
+
+## 常见问题
+
+### 构建速度慢
+
+**解决方案:**
+- 减少不必要的图片和资源
+- 使用 `--incremental` 模式
+- 拆分大型文档为多个小文件
+
+### 翻译质量不高
+
+**解决方案:**
+- 提供上下文给 AI 翻译
+- 建立术语表提高一致性
+- 人工校对关键内容
+
+### 导航结构复杂
+
+**解决方案:**
+- 保持扁平化目录结构
+- 使用清晰的标题层级
+- 提供搜索功能

package/demo/src/config.md

@@ -0,0 +1,160 @@
+# 配置指南
+
+ZEN 的设计理念是极简主义，因此配置非常简单。
+
+## 基本配置
+
+### 命令行参数
+
+```bash
+zengen <src-dir> --out <dist-dir> [options]
+```
+
+**可用选项:**
+- `--out, -o`: 输出目录（必需）
+- `--template, -t`: 自定义模板文件
+- `--watch, -w`: 监听文件变化并自动重建
+- `--verbose, -v`: 显示详细日志
+- `--help, -h`: 显示帮助信息
+
+### 配置文件
+
+在项目根目录创建 `zen.config.js` 文件：
+
+```javascript
+module.exports = {
+  srcDir: './docs',
+  outDir: './dist',
+  template: './template.html',
+  i18n: {
+    sourceLang: 'zh-CN',
+    targetLangs: ['en-US', 'ja-JP']
+  },
+  plugins: [
+    'zen-plugin-sitemap',
+    'zen-plugin-search'
+  ]
+};
+```
+
+## 模板配置
+
+### 默认模板
+
+ZEN 使用内置的极简模板，包含：
+- 响应式布局
+- 代码高亮
+- 导航菜单
+- 深色/浅色主题切换
+
+### 自定义模板
+
+创建自定义模板文件 `custom-template.html`：
+
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>{{title}}</title>
+  <link rel="stylesheet" href="/styles.css">
+</head>
+<body>
+  <nav class="sidebar">
+    {{navigation}}
+  </nav>
+  <main class="content">
+    {{content}}
+  </main>
+  <footer>
+    <p>由 ZEN 生成</p>
+  </footer>
+</body>
+</html>
+```
+
+**可用变量:**
+- `{{title}}`: 页面标题
+- `{{content}}`: 转换后的 HTML 内容
+- `{{navigation}}`: 导航菜单 HTML
+- `{{metadata}}`: 页面元数据（JSON 字符串）
+
+## 多语言配置
+
+### 基本配置
+
+```javascript
+// zen.config.js
+module.exports = {
+  i18n: {
+    sourceLang: 'zh-CN',      // 源语言
+    targetLangs: ['en-US'],   // 目标语言
+    apiKey: process.env.OPENAI_API_KEY, // AI 翻译 API 密钥
+    provider: 'openai'        // 翻译服务提供商
+  }
+};
+```
+
+### 翻译文件结构
+
+```
+docs/
+├── index.md           # 源文件
+├── index.en-US.md     # 英文翻译
+└── index.ja-JP.md     # 日文翻译
+```
+
+### 增量翻译
+
+ZEN 支持增量翻译，只会翻译新增或修改的内容：
+
+```bash
+# 首次构建，翻译所有内容
+zengen ./docs --out ./dist
+
+# 修改部分内容后，只翻译修改的部分
+zengen ./docs --out ./dist --incremental
+```
+
+## 高级配置
+
+### 文件过滤
+
+```javascript
+module.exports = {
+  includePattern: '**/*.md',      // 包含的文件模式
+  excludePattern: '**/_*.md',     // 排除的文件模式
+  ignoreHidden: true              // 忽略隐藏文件
+};
+```
+
+### 元数据提取
+
+在 Markdown 文件顶部添加 YAML frontmatter：
+
+```yaml
+---
+title: 页面标题
+description: 页面描述
+author: 作者名
+date: 2024-01-01
+tags: [文档, 教程]
+---
+```
+
+### 自定义处理器
+
+```javascript
+module.exports = {
+  processors: [
+    {
+      name: 'my-processor',
+      beforeParse(content) {
+        // 预处理逻辑
+        return content;
+      }
+    }
+  ]
+};
+```

package/demo/src/index.md

@@ -0,0 +1,46 @@
+# ZEN 文档站点示例
+
+欢迎使用 ZEN 文档构建工具！这是一个极简主义的 Markdown 文档站点生成器。
+
+## 特性
+
+- **极简配置**: 无需复杂的配置文件
+- **内容优先**: 专注于写作，而不是工具配置
+- **智能导航**: 自动生成站点地图和导航
+- **多语言支持**: 支持增量 i18n 翻译
+
+## 快速开始
+
+```bash
+# 安装 zengen
+npm install -g zengen
+
+# 构建文档
+zengen ./docs --out ./dist
+```
+
+## 代码示例
+
+```javascript
+// 这是一个 JavaScript 示例
+const zen = require('zengen');
+
+async function buildDocs() {
+  await zen.build({
+    srcDir: './docs',
+    outDir: './dist'
+  });
+}
+```
+
+```python
+# 这是一个 Python 示例
+def hello_world():
+    print("Hello from ZEN!")
+```
+
+## 下一步
+
+1. 阅读 [API 文档](./api.md)
+2. 查看 [配置指南](./config.md)
+3. 学习 [最佳实践](./best-practices.md)

package/dist/builder.d.ts

@@ -0,0 +1,37 @@
+import { BuildOptions, ZenConfig } from './types';
+export declare class ZenBuilder {
+    private markdownConverter;
+    private templateEngine;
+    private navigationGenerator;
+    private config;
+    constructor(config?: ZenConfig);
+    /**
+     * 构建文档站点
+     */
+    build(options: BuildOptions): Promise<void>;
+    /**
+     * 监听文件变化并自动重建
+     */
+    watch(options: BuildOptions): Promise<void>;
+    /**
+     * 生成站点地图
+     */
+    private generateSitemap;
+    /**
+     * 生成导航 JSON 文件
+     */
+    private generateNavigationJson;
+    /**
+     * 复制静态资源
+     */
+    private copyStaticAssets;
+    /**
+     * 清理输出目录
+     */
+    clean(outDir: string): Promise<void>;
+    /**
+     * 验证配置
+     */
+    validateConfig(config: ZenConfig): string[];
+}
+//# sourceMappingURL=builder.d.ts.map

package/dist/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAA4B,SAAS,EAAE,MAAM,SAAS,CAAC;AAQ5E,qBAAa,UAAU;IACrB,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,mBAAmB,CAAsB;IACjD,OAAO,CAAC,MAAM,CAAiB;gBAEnB,MAAM,GAAE,SAAc;IAOlC;;OAEG;IACG,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAqFjD;;OAEG;IACG,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAmFjD;;OAEG;YACW,eAAe;IAU7B;;OAEG;YACW,sBAAsB;IAUpC;;OAEG;YACW,gBAAgB;IA6B9B;;OAEG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS1C;;OAEG;IACH,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,EAAE;CAuB5C"}