zengen 0.1.36 → 0.2.1

package/.github/workflows/pages.yml

@@ -35,7 +35,7 @@ jobs:
 
       - name: Create documentation site
         run: |
-          npx zengen@latest build --base-url /ZEN
+          npx zengen@latest build --base-url /ZEN --lang zh-Hans --lang en-US
 
       - name: Setup Pages
         uses: actions/configure-pages@v4

package/.zen/meta.json

@@ -1,57 +1,137 @@
 {
   "version": "1.0.0",
-  "timestamp": "2026-01-05T00:00:00.000Z",
+  "options": {
+    "verbose": true,
+    "langs": ["zh-Hans", "en-US"]
+  },
   "files": [
     {
-      "hash": "abc123",
+      "hash": "1b798c44a4f353e47296ca83d5905e37e6aba3e90bbd9bc3b3d34fc12059a2ca",
+      "path": "README.md",
+      "metadata": {
+        "title": "ZEN - Markdown 文档站点构建工具",
+        "summary": "ZEN 是一个极简的静态站点生成工具，专注于将 Markdown 文件夹构建为 HTML 站点，支持智能导航和 AI 驱动的增量翻译，强调内容优先和跨语言支持，无需复杂配置。",
+        "tags": ["Markdown", "静态站点生成", "AI 翻译", "极简主义", "多语言", "文档工具", "ZEN"],
+        "inferred_lang": "zh-Hans",
+        "tokens_used": {
+          "prompt": 650,
+          "completion": 124,
+          "total": 774
+        }
+      }
+    },
+    {
+      "hash": "5ec990146b35e00de2630559126ee07f7cdcddeb23b0e8cab3d85b4181353e26",
+      "path": "docs/advanced-usage.md",
+      "metadata": {
+        "title": "ZEN 高级用法指南",
+        "summary": "本文档介绍了 ZEN 的高级功能，包括自定义 HTML 模板、配置选项（如源目录、输出目录、模板、基础 URL 和多语言支持）以及插件系统，帮助用户扩展和定制 ZEN 工具。",
+        "tags": ["ZEN", "高级用法", "自定义模板", "配置选项", "插件系统", "文档生成", "多语言支持"],
+        "inferred_lang": "zh-Hans",
+        "tokens_used": {
+          "prompt": 464,
+          "completion": 120,
+          "total": 584
+        }
+      }
+    },
+    {
+      "hash": "01d04f7c17b4a541ead9d759d877b30b403e15b849182a49eb1f62bd29ecd18c",
+      "path": "docs/deployment/github-pages.md",
+      "metadata": {
+        "title": "GitHub Pages 部署配置",
+        "summary": "本文档介绍了 ZEN 项目文档站点的 GitHub Pages 部署配置，包括工作流程、触发条件、构建步骤、自定义配置、故障排除和手动触发方法。",
+        "tags": ["GitHub Pages", "部署配置", "工作流程", "文档构建", "故障排除", "ZEN 项目"],
+        "inferred_lang": "zh-Hans",
+        "tokens_used": {
+          "prompt": 1091,
+          "completion": 106,
+          "total": 1197
+        }
+      }
+    },
+    {
+      "hash": "f0c2799126931ccd113a0c45b1e623870b0d4f4f400becf6dd877da8f1011517",
       "path": "docs/getting-started.md",
       "metadata": {
         "title": "快速开始指南",
-        "summary": "本文档介绍如何快速开始使用 ZEN 文档生成器",
-        "tags": ["getting-started", "tutorial", "documentation"],
-        "inferred_date": "2025-12-01",
+        "summary": "本文档介绍如何快速开始使用 ZEN 文档生成器，包括安装步骤、基本用法和主要特性。",
+        "tags": ["ZEN 文档生成器", "快速开始", "安装", "基本用法", "特性", "Markdown", "构建命令"],
         "inferred_lang": "zh-Hans",
         "tokens_used": {
-          "prompt": 100,
-          "completion": 50,
-          "total": 150
+          "prompt": 373,
+          "completion": 94,
+          "total": 467
         }
-      },
-      "lastUpdated": "2026-01-05T00:00:00.000Z"
+      }
     },
     {
-      "hash": "def456",
-      "path": "docs/advanced-usage.md",
+      "hash": "1e96be58d76c60056b708eb5bd8b8b81d7b5845d9cfe0b879d85068a5f11df3a",
+      "path": "docs/guides/best-practices.md",
       "metadata": {
-        "title": "高级用法",
-        "summary": "深入介绍 ZEN 的高级功能和配置选项",
-        "tags": ["advanced", "configuration", "customization"],
-        "inferred_date": "2025-12-15",
+        "title": "ZEN 文档站点最佳实践",
+        "summary": "本文档介绍了使用 ZEN 构建文档站点的最佳实践，涵盖多语言管理、性能优化、部署策略、维护建议、常见问题解决方案和高级技巧，旨在帮助用户高效开发和维护文档。",
+        "tags": ["ZEN", "文档站点", "最佳实践", "性能优化", "部署策略", "多语言管理", "维护建议"],
         "inferred_lang": "zh-Hans",
         "tokens_used": {
-          "prompt": 120,
-          "completion": 60,
-          "total": 180
+          "prompt": 1282,
+          "completion": 116,
+          "total": 1398
         }
-      },
-      "lastUpdated": "2026-01-05T00:00:00.000Z"
+      }
     },
     {
-      "hash": "ghi789",
-      "path": "docs/deployment.md",
+      "hash": "80ae9bed74fc6348a7c1fe9f33e86b65f5d919169721f77bcf0e1bc29fbdb4f9",
+      "path": "docs/guides/config.md",
       "metadata": {
-        "title": "部署指南",
-        "summary": "如何将 ZEN 生成的文档部署到生产环境",
-        "tags": ["deployment", "production", "hosting"],
-        "inferred_date": "2025-12-20",
+        "title": "ZEN 配置指南",
+        "summary": "本文档介绍了 ZEN 工具的配置和使用方法，包括基本命令如构建文档、实时预览和启动开发服务器，以及命令行选项如 --watch、--serve 和 --port 的详细说明。",
+        "tags": ["ZEN", "配置指南", "命令行", "文档构建", "开发服务器", "极简主义"],
         "inferred_lang": "zh-Hans",
         "tokens_used": {
-          "prompt": 80,
-          "completion": 40,
-          "total": 120
+          "prompt": 669,
+          "completion": 109,
+          "total": 778
+        }
+      }
+    },
+    {
+      "hash": "fdfca9b960d0eaa8b2b96fe988ead7481d2c0b16f66ebc94fb477139b4178cdc",
+      "path": "docs/guides/index.md",
+      "metadata": {
+        "title": "ZEN 文档站点示例",
+        "summary": "介绍 ZEN 文档构建工具，一个极简主义的 Markdown 文档站点生成器，包括特性、快速开始指南、代码示例和下一步学习资源。",
+        "tags": [
+          "ZEN",
+          "文档构建工具",
+          "Markdown",
+          "站点生成器",
+          "快速开始",
+          "代码示例",
+          "多语言支持"
+        ],
+        "inferred_lang": "zh-Hans",
+        "tokens_used": {
+          "prompt": 567,
+          "completion": 108,
+          "total": 675
+        }
+      }
+    },
+    {
+      "hash": "6124ea88edec5bde737b26b21f71ecfeffe4e73151784856edf813ee231a4baa",
+      "path": "docs/testing/test-document.md",
+      "metadata": {
+        "title": "Test Document",
+        "summary": "这是一个测试文档，内容为空，仅包含标题。",
+        "tags": ["测试", "文档", "示例"],
+        "inferred_lang": "en-US",
+        "tokens_used": {
+          "prompt": 265,
+          "completion": 58,
+          "total": 323
         }
-      },
-      "lastUpdated": "2026-01-05T00:00:00.000Z"
+      }
     }
   ]
 }

package/.zen/src/en-US/01d04f7c17b4a541ead9d759d877b30b403e15b849182a49eb1f62bd29ecd18c.md

@@ -0,0 +1,120 @@
+---
+title: GitHub Pages Deployment Configuration
+summary: This document describes the GitHub Pages deployment configuration for the ZEN project documentation site, including workflow, trigger conditions, build steps, custom configuration, troubleshooting, and manual trigger methods.
+tags:
+  - GitHub Pages
+  - Deployment Configuration
+  - Workflow
+  - Documentation Build
+  - Troubleshooting
+  - ZEN Project
+inferred_lang: en-US
+---
+
+# GitHub Pages Deployment Configuration
+
+This directory contains the GitHub Pages deployment configuration for the ZEN project documentation site.
+
+## Workflow
+
+### `pages.yml`
+
+This workflow automatically builds the ZEN project documentation site and deploys it to GitHub Pages.
+
+**Trigger Conditions:**
+
+- Push to the `main` branch (when changes occur in `demo/src/`, `package.json`, or workflow files)
+- Pull Request targeting the `main` branch
+- Manual trigger
+
+**Workflow Steps:**
+
+1.  **Checkout code**: Check out code from the remote branch to ensure code synchronization.
+2.  **Set up Node.js**: Configure the Node.js 20.x environment.
+3.  **Install dependencies**: Install project dependencies using `npm ci`.
+4.  **Build zengen**: Build the local zengen package.
+5.  **Install zengen**: Install the locally built zengen as a global tool.
+6.  **Test zengen CLI**: Verify the CLI tool functions correctly.
+7.  **Build documentation site**: Build the documentation using `cd demo/src && zengen build`, outputting to the `.zen/dist` directory.
+8.  **Configure Pages**: Set up GitHub Pages.
+9.  **Upload artifact**: Upload the built documentation site as a Pages artifact.
+10. **Deploy to GitHub Pages**: Automatically deploy to GitHub Pages.
+
+## Accessing the Documentation Site
+
+After successful deployment, the documentation site will be accessible at the following URL:
+
+```
+https://[username].github.io/[repository-name]/
+```
+
+## Custom Configuration
+
+### Custom Domain
+
+If a custom domain is needed, you can add a CNAME file after the build step:
+
+```yaml
+# Create CNAME file (if a custom domain is needed)
+echo "docs.example.com" > docs-dist/CNAME
+```
+
+### Build Options
+
+Currently used build command:
+
+```bash
+cd demo/src
+zengen build --verbose
+```
+
+Available options:
+
+- `--verbose`: Show verbose output.
+- `--watch`: Watch mode (not suitable for CI/CD).
+- `--template`: Specify a custom template file.
+- `--config`: Specify a configuration file.
+
+### Environment Variables
+
+The workflow uses the following environment variables:
+
+- `GITHUB_TOKEN`: Automatically provided GitHub token.
+- `NODE_VERSION`: Node.js version (defaults to 20.x).
+
+## Troubleshooting
+
+### Build Failure
+
+1.  **Check Node.js version**: Ensure a supported Node.js version is used.
+2.  **Verify dependency installation**: Ensure `npm ci` executes successfully.
+3.  **Check build output**: Review the verbose output of `zengen build`.
+4.  **CLI output directory issue**: ZEN now forces output to the `.zen/dist` directory and no longer supports the `--out` parameter.
+
+### Deployment Failure
+
+1.  **Check permissions**: Ensure the workflow has correct write permissions for Pages.
+2.  **Verify artifact**: Ensure the `.zen/dist` directory contains valid HTML files.
+3.  **Review logs**: Check GitHub Actions logs for detailed error messages.
+
+### Documentation Not Updated
+
+1.  **Check trigger conditions**: Ensure files in the `demo/src/` directory were modified.
+2.  **Wait for deployment completion**: GitHub Pages deployment may take a few minutes.
+3.  **Clear browser cache**: The browser may be caching an old version.
+
+## Manual Trigger
+
+Deployment can be manually triggered via the GitHub Actions interface:
+
+1.  Go to the repository's "Actions" tab.
+2.  Select the "Deploy to GitHub Pages" workflow.
+3.  Click the "Run workflow" button.
+4.  Select the branch and run.
+
+## Related Files
+
+- `demo/src/`: Documentation source files (Markdown format).
+- `package.json`: Project configuration and dependencies.
+- `src/cli.ts`: zengen CLI tool implementation.
+- `src/builder.ts`: Documentation builder implementation.

package/.zen/src/en-US/1b798c44a4f353e47296ca83d5905e37e6aba3e90bbd9bc3b3d34fc12059a2ca.md

@@ -0,0 +1,75 @@
+---
+title: ZEN - Markdown Documentation Site Builder
+summary: ZEN is a minimalist static site generator focused on building HTML sites from Markdown folders. It supports intelligent navigation and AI-powered incremental translation, emphasizing content-first and cross-language support without complex configuration.
+tags:
+  - Markdown
+  - Static Site Generation
+  - AI Translation
+  - Minimalism
+  - Multilingual
+  - Documentation Tool
+  - ZEN
+inferred_lang: en-US
+---
+
+# ZEN - A Concise Markdown Documentation Site Builder
+
+> 📖 **Reading Note**: This README is the Chinese version. The English version will be automatically generated by AI translation.
+
+## Project Motivation
+
+### Return to Content
+
+I enjoy contemplation but dislike complex build tools, fiddling with intricate documentation configurations, and complicated structures.
+
+### Return to Native Language
+
+Life is short, I use AI translation. Stay connected with the world.
+
+## Core Features
+
+1. **Static Site Generation**
+   - Build a static HTML site from any folder containing Markdown files.
+
+2. **Intelligent Navigation**
+   - Generate site maps and navigation without needing to preserve the original directory structure of the Markdown source files.
+
+3. **Incremental i18n Translation**
+   - Use LLM for incremental i18n translation, allowing users to write Markdown in their native language while supporting multilingual audiences.
+
+## Design Philosophy
+
+- **Minimalism**: Minimal configuration, maximum flexibility.
+- **Content-First**: Focus on writing, not tool configuration.
+- **AI-Powered**: Leverage AI for translation and content organization.
+- **Cross-Language**: Support multilingual content creation and display.
+
+## Quick Start
+
+### Recommended Usage
+
+**It is recommended that users switch to the directory containing Markdown files and directly use the following command to start building:**
+
+```bash
+npx zengen build
+```
+
+### Other Usages
+
+1. **Live Preview (Watch for file changes)**:
+
+```bash
+npx zengen build --watch
+```
+
+2. **View more parameters or help**:
+
+```bash
+npx zengen
+```
+
+**Note**: ZEN enforces using the current directory as the source directory and outputs to the `.zen/dist` directory. Specifying source and output directory parameters is no longer supported.
+
+---
+
+**ZEN** - Let documentation return to its essence, let writing return to tranquility.

package/.zen/src/en-US/1e96be58d76c60056b708eb5bd8b8b81d7b5845d9cfe0b879d85068a5f11df3a.md

@@ -0,0 +1,189 @@
+---
+title: ZEN Documentation Site Best Practices
+summary: This document introduces best practices for building documentation sites using ZEN, covering multilingual management, performance optimization, deployment strategies, maintenance recommendations, common issue solutions, and advanced techniques, aiming to help users efficiently develop and maintain documentation.
+tags:
+  - ZEN
+  - Documentation Site
+  - Best Practices
+  - Performance Optimization
+  - Deployment Strategy
+  - Multilingual Management
+  - Maintenance Recommendations
+inferred_lang: en-US
+---
+
+# Best Practices
+
+This document introduces best practices for building documentation sites using ZEN.
+
+## Multilingual Management
+
+### Translation Strategy
+
+1.  **Primary Language First**: Write the complete documentation in your native language first.
+2.  **Incremental Translation**: Only translate modified parts after each update.
+3.  **Terminology Consistency**: Create a glossary to maintain translation consistency.
+4.  **Human Review**: It is recommended to perform human review after AI translation.
+
+## Performance Optimization
+
+### Build Optimization
+
+1.  **Incremental Builds**: Use `--watch` mode for development.
+2.  **Cache Utilization**: ZEN automatically caches processing results.
+3.  **Parallel Processing**: Files are automatically processed in parallel on multi-core CPUs.
+
+### Development Workflow
+
+```bash
+# Watch for changes during development
+cd docs
+npx zengen build --watch
+
+# Start development server
+npx zengen build --watch --serve
+
+# Production build
+npx zengen build
+```
+
+## Deployment Strategy
+
+### CI/CD Integration
+
+#### GitHub Actions Example
+
+```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
+```
+
+#### Custom Deployment Script
+
+```bash
+#!/bin/bash
+# deploy-docs.sh
+
+# Switch to the documentation directory
+cd docs
+
+# Build documentation
+npx zengen build
+
+# Sync to server
+rsync -avz .zen/dist/ user@server:/var/www/docs/
+
+# Clean cache
+rm -rf .zen/cache
+```
+
+### Cloud Deployment Options
+
+- **GitHub Pages**: Free hosting for documentation.
+- **Vercel**: Automatic deployment for static sites.
+- **Netlify**: Supports form handling and redirects.
+- **AWS S3 + CloudFront**: Enterprise-grade static hosting.
+
+## Maintenance Recommendations
+
+### Regular Updates
+
+1.  **Content Review**: Check documentation accuracy monthly.
+2.  **Link Checking**: Regularly check for broken links.
+3.  **Performance Monitoring**: Monitor page load speed.
+4.  **User Feedback**: Collect user feedback to improve documentation.
+
+### Version Control
+
+1.  **Documentation Versioning**: Synchronize with software versions.
+2.  **Changelog**: Record documentation update history.
+3.  **Rollback Mechanism**: Support quick rollback to previous versions.
+
+## Common Issues
+
+### Slow Build Speed
+
+**Solutions:**
+
+- Reduce unnecessary images and resources.
+- Use `--watch` mode for incremental development.
+- Split large documents into multiple smaller files.
+- Disable unnecessary processors.
+
+### Poor Translation Quality
+
+**Solutions:**
+
+- Provide context to the AI translator.
+- Create a glossary to improve consistency.
+- Perform human review for critical content.
+- Adjust translation prompts.
+
+### Complex Navigation Structure
+
+**Solutions:**
+
+- Maintain a flat directory structure.
+- Use clear heading hierarchies.
+- Provide search functionality.
+- Use sidebar navigation appropriately.
+
+### High Memory Usage
+
+**Solutions:**
+
+- Reduce the number of files processed simultaneously.
+- Disable caching (not recommended).
+- Increase system memory.
+- Process large documents in batches.
+
+## Advanced Techniques
+
+### Custom Template Techniques
+
+1.  **Responsive Design**: Ensure the template displays correctly on mobile devices.
+2.  **Theme Switching**: Implement dark/light themes.
+3.  **Code Highlighting**: Integrate highlight.js or other highlighting libraries.
+4.  **Search Functionality**: Add client-side search.
+
+### Integrating Other Tools
+
+1.  **Image Optimization**: Use sharp or imagemin to optimize images.
+2.  **SEO Optimization**: Add meta tags and structured data.
+3.  **Analytics Integration**: Integrate Google Analytics or Plausible.
+4.  **CDN Acceleration**: Use a CDN to accelerate static resources.
+
+### Monitoring and Logging
+
+1.  **Build Logs**: Use `--verbose` to view detailed logs.
+2.  **Error Monitoring**: Set up error monitoring and alerts.
+3.  **Performance Monitoring**: Monitor build time and resource usage.
+4.  **User Analytics**: Analyze documentation usage.

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        |