zengen 0.2.1 → 0.2.3

package/docs/advanced-usage.md

@@ -1,39 +0,0 @@
-# 高级用法
-
-深入介绍 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/docs/deployment/github-pages.md

@@ -1,107 +0,0 @@
-# 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/docs/getting-started.md

@@ -1,26 +0,0 @@
-# 快速开始指南
-
-本文档介绍如何快速开始使用 ZEN 文档生成器。
-
-## 安装
-
-```bash
-npm install -g zengen
-```
-
-## 基本用法
-
-1. 创建文档目录
-2. 编写 Markdown 文件
-3. 运行构建命令
-
-```bash
-zengen build --src ./docs --out ./dist
-```
-
-## 特性
-
-- 极简配置
-- 内置响应式模板
-- AI 辅助元数据提取
-- 多语言支持

package/docs/guides/best-practices.md

@@ -1,175 +0,0 @@
-# 最佳实践
-
-本文档介绍使用 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/docs/guides/config.md

@@ -1,48 +0,0 @@
-# 配置指南
-
-ZEN 的设计理念是极简主义，因此配置非常简单。
-
-## 命令行使用
-
-### 基本命令
-
-```bash
-# 构建文档（推荐使用方式）
-npx zengen build
-
-# 实时预览（监听文件变化）
-npx zengen build --watch
-
-# 启动开发服务器（需要 --watch）
-npx zengen build --watch --serve
-
-# 自定义端口
-npx zengen build --watch --serve --port 8080
-
-# 显示详细日志
-npx zengen build --verbose
-
-# 设置基础 URL
-npx zengen build --base-url /my-docs
-
-# 查看帮助
-npx zengen
-```
-
-**重要说明：**
-
-- ZEN 强制使用当前目录作为源目录，输出到 `.zen/dist` 目录
-- 不再支持通过命令行参数指定源目录和输出目录
-- 使用 `--watch` 模式时，修改文件会自动重建
-
-### 命令行选项
-
-| 选项         | 简写 | 描述                             | 默认值      |
-| ------------ | ---- | -------------------------------- | ----------- |
-| `--watch`    | `-w` | 监听文件变化并自动重建           | `false`     |
-| `--serve`    | `-s` | 启动开发服务器（需要 `--watch`） | `false`     |
-| `--port`     | `-p` | 开发服务器端口                   | `3000`      |
-| `--host`     |      | 开发服务器主机                   | `localhost` |
-| `--verbose`  | `-v` | 显示详细日志                     | `false`     |
-| `--base-url` |      | 站点基础 URL                     | 无          |
-| `--help`     | `-h` | 显示帮助信息                     | 无          |

package/docs/guides/index.md

@@ -1,51 +0,0 @@
-# ZEN 文档站点示例
-
-欢迎使用 ZEN 文档构建工具！这是一个极简主义的 Markdown 文档站点生成器。
-
-## 特性
-
-- **极简配置**: 无需复杂的配置文件
-- **内容优先**: 专注于写作，而不是工具配置
-- **智能导航**: 自动生成站点地图和导航
-- **多语言支持**: 支持增量 i18n 翻译
-
-## 快速开始
-
-```bash
-# 使用 npx 构建文档（推荐）
-npx zengen build
-
-# 实时预览（监听文件变化）
-npx zengen build --watch
-
-# 查看更多参数或帮助
-npx zengen
-```
-
-**注意**：ZEN 强制使用当前目录作为源目录，输出到 `.zen/dist` 目录。不再支持指定源目录和输出目录参数。
-
-## 代码示例
-
-```javascript
-// 这是一个 JavaScript 示例
-const zen = require('zengen');
-
-async function buildDocs() {
-  await zen.build({
-    // ZEN 现在强制使用当前目录作为源目录
-    // 输出到 .zen/dist 目录
-  });
-}
-```
-
-```python
-# 这是一个 Python 示例
-def hello_world():
-    print("Hello from ZEN!")
-```
-
-## 下一步
-
-1. 阅读 [API 文档](./api.md)
-2. 查看 [配置指南](./config.md)
-3. 学习 [最佳实践](./best-practices.md)

package/docs/testing/test-document.md

@@ -1 +0,0 @@
-# Test Document