zengen 0.1.35 → 0.2.0

package/.zen/src/en-US/5ec990146b35e00de2630559126ee07f7cdcddeb23b0e8cab3d85b4181353e26.md

@@ -0,0 +1,53 @@
+---
+title: ZEN Advanced Usage Guide
+summary: This document introduces the advanced features of ZEN, including custom HTML templates, configuration options (such as source directory, output directory, template, base URL, and multilingual support), and the plugin system, helping users extend and customize the ZEN tool.
+tags:
+  - ZEN
+  - Advanced Usage
+  - Custom Templates
+  - Configuration Options
+  - Plugin System
+  - Documentation Generation
+  - Multilingual Support
+inferred_lang: en-US
+---
+
+# Advanced Usage
+
+An in-depth introduction to the advanced features and configuration options of ZEN.
+
+## Custom Templates
+
+ZEN supports custom HTML templates:
+
+```bash
+zengen build --src ./docs --out ./dist --template ./custom-template.html
+```
+
+## Configuration Options
+
+Can be configured in the `.zenrc` file:
+
+```json
+{
+  "srcDir": "./docs",
+  "outDir": "./dist",
+  "template": "./template.html",
+  "baseUrl": "https://example.com",
+  "i18n": {
+    "sourceLang": "zh-Hans",
+    "targetLangs": ["en-US", "ja-JP"]
+  }
+}
+```
+
+## Plugin System
+
+ZEN supports plugin extensions:
+
+```typescript
+interface MarkdownProcessor {
+  beforeParse?(content: string, fileInfo: FileInfo): string | Promise<string>;
+  afterParse?(html: string, fileInfo: FileInfo): string | Promise<string>;
+}
+```

package/.zen/src/en-US/6124ea88edec5bde737b26b21f71ecfeffe4e73151784856edf813ee231a4baa.md

@@ -0,0 +1,11 @@
+---
+title: Test Document
+summary: 这是一个测试文档，内容为空，仅包含标题。
+tags:
+  - 测试
+  - 文档
+  - 示例
+inferred_lang: en-US
+---
+
+# Test Document

package/.zen/src/en-US/80ae9bed74fc6348a7c1fe9f33e86b65f5d919169721f77bcf0e1bc29fbdb4f9.md

@@ -0,0 +1,61 @@
+---
+title: ZEN Configuration Guide
+summary: This document introduces the configuration and usage of the ZEN tool, including basic commands such as building documentation, live preview, and starting a development server, as well as detailed explanations of command-line options like --watch, --serve, and --port.
+tags:
+  - ZEN
+  - Configuration Guide
+  - Command Line
+  - Documentation Build
+  - Development Server
+  - Minimalism
+inferred_lang: en-US
+---
+
+# Configuration Guide
+
+ZEN is designed with a minimalist philosophy, making its configuration very simple.
+
+## Command Line Usage
+
+### Basic Commands
+
+```bash
+# Build documentation (recommended usage)
+npx zengen build
+
+# Live preview (watch for file changes)
+npx zengen build --watch
+
+# Start development server (requires --watch)
+npx zengen build --watch --serve
+
+# Custom port
+npx zengen build --watch --serve --port 8080
+
+# Show verbose logs
+npx zengen build --verbose
+
+# Set base URL
+npx zengen build --base-url /my-docs
+
+# View help
+npx zengen
+```
+
+**Important Notes:**
+
+- ZEN enforces the use of the current directory as the source directory, outputting to the `.zen/dist` directory
+- Specifying source and output directories via command-line arguments is no longer supported
+- When using `--watch` mode, modifying files triggers automatic rebuilds
+
+### Command Line Options
+
+| Option       | Short | Description                                      | Default     |
+| ------------ | ----- | ------------------------------------------------ | ----------- |
+| `--watch`    | `-w`  | Watch for file changes and rebuild automatically | `false`     |
+| `--serve`    | `-s`  | Start development server (requires `--watch`)    | `false`     |
+| `--port`     | `-p`  | Development server port                          | `3000`      |
+| `--host`     |       | Development server host                          | `localhost` |
+| `--verbose`  | `-v`  | Show verbose logs                                | `false`     |
+| `--base-url` |       | Site base URL                                    | None        |
+| `--help`     | `-h`  | Show help information                            | None        |

package/.zen/src/en-US/f0c2799126931ccd113a0c45b1e623870b0d4f4f400becf6dd877da8f1011517.md

@@ -0,0 +1,41 @@
+---
+title: Quick Start Guide
+summary: This document introduces the quick start method for the ZEN documentation generator, including installation steps, basic usage workflow, and main features, helping users get started quickly.
+tags:
+  - ZEN Documentation Generator
+  - Quick Start
+  - Installation
+  - Basic Usage
+  - Features
+  - Markdown
+  - AI-Assisted
+  - Multi-language Support
+inferred_lang: en-US
+---
+
+# Quick Start Guide
+
+This document introduces how to quickly get started with the ZEN documentation generator.
+
+## Installation
+
+```bash
+npm install -g zengen
+```
+
+## Basic Usage
+
+1. Create a documentation directory
+2. Write Markdown files
+3. Run the build command
+
+```bash
+zengen build --src ./docs --out ./dist
+```
+
+## Features
+
+- Minimal configuration
+- Built-in responsive templates
+- AI-assisted metadata extraction
+- Multi-language support

package/.zen/src/en-US/fdfca9b960d0eaa8b2b96fe988ead7481d2c0b16f66ebc94fb477139b4178cdc.md

@@ -0,0 +1,65 @@
+---
+title: ZEN Documentation Site Example
+summary: Introducing ZEN documentation builder, a minimalist Markdown documentation site generator, including features such as minimal configuration, content-first approach, intelligent navigation, multilingual support, as well as a quick start guide and code examples.
+tags:
+  - ZEN
+  - Documentation Builder
+  - Markdown
+  - Site Generator
+  - Minimalism
+  - Quick Start
+  - Multilingual Support
+inferred_lang: en-US
+---
+
+# ZEN Documentation Site Example
+
+Welcome to the ZEN documentation builder! This is a minimalist Markdown documentation site generator.
+
+## Features
+
+- **Minimal Configuration**: No complex configuration files required
+- **Content-First**: Focus on writing, not tool configuration
+- **Intelligent Navigation**: Automatically generates site maps and navigation
+- **Multilingual Support**: Supports incremental i18n translation
+
+## Quick Start
+
+```bash
+# Build documentation using npx (recommended)
+npx zengen build
+
+# Live preview (watches for file changes)
+npx zengen build --watch
+
+# View more parameters or help
+npx zengen
+```
+
+**Note**: ZEN enforces the use of the current directory as the source directory and outputs to the `.zen/dist` directory. Specifying source and output directory parameters is no longer supported.
+
+## Code Examples
+
+```javascript
+// This is a JavaScript example
+const zen = require('zengen');
+
+async function buildDocs() {
+  await zen.build({
+    // ZEN now enforces using the current directory as the source directory
+    // Outputs to the .zen/dist directory
+  });
+}
+```
+
+```python
+# This is a Python example
+def hello_world():
+    print("Hello from ZEN!")
+```
+
+## Next Steps
+
+1. Read the [API Documentation](./api.md)
+2. Check the [Configuration Guide](./config.md)
+3. Learn about [Best Practices](./best-practices.md)

package/.zen/src/zh-Hans/01d04f7c17b4a541ead9d759d877b30b403e15b849182a49eb1f62bd29ecd18c.md

@@ -0,0 +1,120 @@
+---
+title: GitHub Pages 部署配置
+summary: 本文档介绍了 ZEN 项目文档站点的 GitHub Pages 部署配置，包括工作流程、触发条件、构建步骤、自定义配置、故障排除和手动触发方法。
+tags:
+  - GitHub Pages
+  - 部署配置
+  - 工作流程
+  - 文档构建
+  - 故障排除
+  - ZEN 项目
+inferred_lang: zh-Hans
+---
+
+# GitHub Pages 部署配置
+
+此目录包含 ZEN 项目文档站点的 GitHub Pages 部署配置。
+
+## 工作流程
+
+### `pages.yml`
+
+此工作流程会自动构建 ZEN 项目的文档站点并部署到 GitHub Pages。
+
+**触发条件：**
+
+- 推送到 `main` 分支（当 `demo/src/`、`package.json` 或工作流程文件发生变化时）
+- 针对 `main` 分支的 Pull Request
+- 手动触发
+
+**工作流程步骤：**
+
+1. **检出代码**：从远程分支检出代码，确保代码同步
+2. **设置 Node.js**：配置 Node.js 20.x 环境
+3. **安装依赖**：使用 `npm ci` 安装项目依赖
+4. **构建 zengen**：构建本地 zengen 包
+5. **安装 zengen**：将本地构建的 zengen 安装为全局工具
+6. **测试 zengen CLI**：验证 CLI 工具正常工作
+7. **构建文档站点**：使用 `cd demo/src && zengen build` 构建文档，输出到 `.zen/dist` 目录
+8. **配置 Pages**：设置 GitHub Pages
+9. **上传制品**：将构建的文档站点上传为 Pages 制品
+10. **部署到 GitHub Pages**：自动部署到 GitHub Pages
+
+## 访问文档站点
+
+部署成功后，文档站点将可通过以下 URL 访问：
+
+```
+https://[用户名].github.io/[仓库名]/
+```
+
+## 自定义配置
+
+### 自定义域名
+
+如果需要使用自定义域名，可以在构建步骤后添加 CNAME 文件：
+
+```yaml
+# 创建 CNAME 文件（如果需要自定义域名）
+echo "docs.example.com" > docs-dist/CNAME
+```
+
+### 构建选项
+
+当前使用的构建命令：
+
+```bash
+cd demo/src
+zengen build --verbose
+```
+
+可用的选项：
+
+- `--verbose`：显示详细输出
+- `--watch`：监听模式（不适用于 CI/CD）
+- `--template`：指定自定义模板文件
+- `--config`：指定配置文件
+
+### 环境变量
+
+工作流程使用以下环境变量：
+
+- `GITHUB_TOKEN`：自动提供的 GitHub 令牌
+- `NODE_VERSION`：Node.js 版本（默认为 20.x）
+
+## 故障排除
+
+### 构建失败
+
+1. **检查 Node.js 版本**：确保使用支持的 Node.js 版本
+2. **验证依赖安装**：确保 `npm ci` 成功执行
+3. **检查构建输出**：查看 `zengen build` 的详细输出
+4. **CLI 输出目录问题**：ZEN 现在强制输出到 `.zen/dist` 目录，不再支持 `--out` 参数。
+
+### 部署失败
+
+1. **检查权限**：确保工作流程有正确的 Pages 写入权限
+2. **验证制品**：确保 `.zen/dist` 目录包含有效的 HTML 文件
+3. **查看日志**：检查 GitHub Actions 日志获取详细错误信息
+
+### 文档未更新
+
+1. **检查触发条件**：确保修改了 `demo/src/` 目录下的文件
+2. **等待部署完成**：GitHub Pages 部署可能需要几分钟
+3. **清除浏览器缓存**：浏览器可能缓存了旧版本
+
+## 手动触发
+
+可以通过 GitHub Actions 界面手动触发部署：
+
+1. 进入仓库的 "Actions" 标签页
+2. 选择 "Deploy to GitHub Pages" 工作流程
+3. 点击 "Run workflow" 按钮
+4. 选择分支并运行
+
+## 相关文件
+
+- `demo/src/`：文档源文件（Markdown 格式）
+- `package.json`：项目配置和依赖
+- `src/cli.ts`：zengen CLI 工具实现
+- `src/builder.ts`：文档构建器实现

package/.zen/src/zh-Hans/1b798c44a4f353e47296ca83d5905e37e6aba3e90bbd9bc3b3d34fc12059a2ca.md

@@ -0,0 +1,77 @@
+---
+title: ZEN - Markdown 文档站点构建工具
+summary:
+  ZEN 是一个极简的静态站点生成工具，专注于将 Markdown 文件夹构建为 HTML 站点，支持智能导航和 AI
+  驱动的增量翻译，强调内容优先和跨语言支持，无需复杂配置。
+tags:
+  - Markdown
+  - 静态站点生成
+  - AI 翻译
+  - 极简主义
+  - 多语言
+  - 文档工具
+  - ZEN
+inferred_lang: zh-Hans
+---
+
+# ZEN - 简洁的 Markdown 文档站点构建工具
+
+> 📖 **阅读提示**: 本 README 为中文版本。英文版本将由 AI 自动翻译生成。
+
+## 项目初衷
+
+### 回归内容
+
+我喜欢沉思，但不想要配置复杂的构建工具，折腾复杂的文档配置，不喜欢复杂的结构。
+
+### 回归母语
+
+生命苦短，我用 AI 翻译。与世界保持连接。
+
+## 基本功能
+
+1. **静态站点生成**
+   - 将任意一个包含 Markdown 的文件夹构建成一个静态 HTML 站点
+
+2. **智能导航**
+   - 生成站点地图和导航，不需要保持原始的 Markdown 源文件的目录结构
+
+3. **增量 i18n 翻译**
+   - 使用 LLM 进行增量 i18n 翻译，让用户使用母语编写 Markdown，但是用户可以是多语言的
+
+## 设计理念
+
+- **极简主义**: 最少的配置，最大的灵活性
+- **内容优先**: 专注于写作，而不是工具配置
+- **AI 赋能**: 利用 AI 处理翻译和内容组织
+- **跨语言**: 支持多语言内容创作和展示
+
+## 快速开始
+
+### 推荐使用方式
+
+**推荐用户切换到包含 Markdown 文件的目录下，直接使用以下命令开始构建：**
+
+```bash
+npx zengen build
+```
+
+### 其他用法
+
+1. **实时预览（监听文件变化）**：
+
+```bash
+npx zengen build --watch
+```
+
+2. **查看更多参数或帮助**：
+
+```bash
+npx zengen
+```
+
+**注意**：ZEN 强制使用当前目录作为源目录，输出到 `.zen/dist` 目录。不再支持指定源目录和输出目录参数。
+
+---
+
+**ZEN** - 让文档回归本质，让写作回归宁静。

package/.zen/src/zh-Hans/1e96be58d76c60056b708eb5bd8b8b81d7b5845d9cfe0b879d85068a5f11df3a.md

@@ -0,0 +1,189 @@
+---
+title: ZEN 文档站点最佳实践
+summary: 本文档介绍了使用 ZEN 构建文档站点的最佳实践，涵盖多语言管理、性能优化、部署策略、维护建议、常见问题解决方案和高级技巧，旨在帮助用户高效开发和维护文档。
+tags:
+  - ZEN
+  - 文档站点
+  - 最佳实践
+  - 性能优化
+  - 部署策略
+  - 多语言管理
+  - 维护建议
+inferred_lang: zh-Hans
+---
+
+# 最佳实践
+
+本文档介绍使用 ZEN 构建文档站点的最佳实践。
+
+## 多语言管理
+
+### 翻译策略
+
+1. **主语言优先**: 先用母语完整编写文档
+2. **增量翻译**: 每次更新后只翻译修改部分
+3. **术语一致**: 建立术语表保持翻译一致性
+4. **人工校对**: AI 翻译后建议人工校对
+
+## 性能优化
+
+### 构建优化
+
+1. **增量构建**: 使用 `--watch` 模式开发
+2. **缓存利用**: ZEN 会自动缓存处理结果
+3. **并行处理**: 多核 CPU 自动并行处理文件
+
+### 开发工作流
+
+```bash
+# 开发时监听变化
+cd docs
+npx zengen build --watch
+
+# 启动开发服务器
+npx zengen build --watch --serve
+
+# 生产构建
+npx zengen build
+```
+
+## 部署策略
+
+### CI/CD 集成
+
+#### GitHub Actions 示例
+
+```yaml
+name: Build and Deploy Documentation
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+
+      - name: Build documentation
+        run: |
+          cd docs
+          npx zengen build --base-url /my-docs
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/.zen/dist
+```
+
+#### 自定义部署脚本
+
+```bash
+#!/bin/bash
+# deploy-docs.sh
+
+# 切换到文档目录
+cd docs
+
+# 构建文档
+npx zengen build
+
+# 同步到服务器
+rsync -avz .zen/dist/ user@server:/var/www/docs/
+
+# 清理缓存
+rm -rf .zen/cache
+```
+
+### 云部署选项
+
+- **GitHub Pages**: 免费托管文档
+- **Vercel**: 自动部署静态站点
+- **Netlify**: 支持表单处理和重定向
+- **AWS S3 + CloudFront**: 企业级静态托管
+
+## 维护建议
+
+### 定期更新
+
+1. **内容审核**: 每月检查文档准确性
+2. **链接检查**: 定期检查死链
+3. **性能监控**: 监控页面加载速度
+4. **用户反馈**: 收集用户反馈改进文档
+
+### 版本控制
+
+1. **文档版本化**: 与软件版本同步
+2. **变更日志**: 记录文档更新历史
+3. **回滚机制**: 支持快速回滚到旧版本
+
+## 常见问题
+
+### 构建速度慢
+
+**解决方案:**
+
+- 减少不必要的图片和资源
+- 使用 `--watch` 模式进行增量开发
+- 拆分大型文档为多个小文件
+- 禁用不需要的处理器
+
+### 翻译质量不高
+
+**解决方案:**
+
+- 提供上下文给 AI 翻译
+- 建立术语表提高一致性
+- 人工校对关键内容
+- 调整翻译提示词
+
+### 导航结构复杂
+
+**解决方案:**
+
+- 保持扁平化目录结构
+- 使用清晰的标题层级
+- 提供搜索功能
+- 合理使用侧边栏导航
+
+### 内存使用过高
+
+**解决方案:**
+
+- 减少同时处理的文件数量
+- 禁用缓存（不推荐）
+- 增加系统内存
+- 分批处理大型文档
+
+## 高级技巧
+
+### 自定义模板技巧
+
+1. **响应式设计**: 确保模板在移动设备上正常显示
+2. **主题切换**: 实现深色/浅色主题
+3. **代码高亮**: 集成 highlight.js 或其他高亮库
+4. **搜索功能**: 添加客户端搜索
+
+### 集成其他工具
+
+1. **图片优化**: 使用 sharp 或 imagemin 优化图片
+2. **SEO 优化**: 添加 meta 标签和结构化数据
+3. **分析集成**: 集成 Google Analytics 或 Plausible
+4. **CDN 加速**: 使用 CDN 加速静态资源
+
+### 监控和日志
+
+1. **构建日志**: 使用 `--verbose` 查看详细日志
+2. **错误监控**: 设置错误监控和告警
+3. **性能监控**: 监控构建时间和资源使用
+4. **用户分析**: 分析文档使用情况

package/.zen/src/zh-Hans/5ec990146b35e00de2630559126ee07f7cdcddeb23b0e8cab3d85b4181353e26.md

@@ -0,0 +1,55 @@
+---
+title: ZEN 高级用法指南
+summary:
+  本文档介绍了 ZEN 的高级功能，包括自定义 HTML 模板、配置选项（如源目录、输出目录、模板、基础 URL
+  和多语言支持）以及插件系统，帮助用户扩展和定制 ZEN 工具。
+tags:
+  - ZEN
+  - 高级用法
+  - 自定义模板
+  - 配置选项
+  - 插件系统
+  - 文档生成
+  - 多语言支持
+inferred_lang: zh-Hans
+---
+
+# 高级用法
+
+深入介绍 ZEN 的高级功能和配置选项。
+
+## 自定义模板
+
+ZEN 支持自定义 HTML 模板：
+
+```bash
+zengen build --src ./docs --out ./dist --template ./custom-template.html
+```
+
+## 配置选项
+
+可以在 `.zenrc` 文件中配置：
+
+```json
+{
+  "srcDir": "./docs",
+  "outDir": "./dist",
+  "template": "./template.html",
+  "baseUrl": "https://example.com",
+  "i18n": {
+    "sourceLang": "zh-Hans",
+    "targetLangs": ["en-US", "ja-JP"]
+  }
+}
+```
+
+## 插件系统
+
+ZEN 支持插件扩展功能：
+
+```typescript
+interface MarkdownProcessor {
+  beforeParse?(content: string, fileInfo: FileInfo): string | Promise<string>;
+  afterParse?(html: string, fileInfo: FileInfo): string | Promise<string>;
+}
+```

package/.zen/src/zh-Hans/6124ea88edec5bde737b26b21f71ecfeffe4e73151784856edf813ee231a4baa.md

@@ -0,0 +1 @@
+# 测试文档