zengen 0.1.36 → 0.2.0

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 @@
+# 测试文档