xfmpress 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.1] - 2026-11-03
+
+### Changed
+
+- English `README.md` is now the default document shown on the npm page;
+  the Chinese version ships as `README_CN.md`, and both link to each other.
+- Documentation split into English/Chinese pairs: `README` / `README_CN`,
+  `INSTALL` / `INSTALL_CN`, `PROGRAM` / `PROGRAM_CN`.
+- Dev server port corrected to `4173` in all docs and scaffolds
+  (previously documented inconsistently as `4000` / `4321`).
+- Package description rewritten in English to match the npm-facing README.
+
+### Fixed
+
+- Docs referenced the wrong install target (`npm i -D xfm`); the installable
+  package is `xfmpress` while the CLI command remains `xfm`.
+- Configuration examples now consistently use the `site: {}` shape with
+  a top-level `outDir`.
+
+## [0.1.0] - 2026-11-02
+
+### Added
+
+- Initial release: zero-dependency static site generator with a shared
+  render pipeline used by both the main thread and worker threads.
+- Multi-threaded page rendering with content-hashed incremental builds.
+- Nunjucks-style template engine compiled to JavaScript functions at build
+  time, with optional-chaining guards generated at compile time.
+- Plugin system with `markdown`, `transformHtml`, `extendContext`,
+  `afterBuild`, `configureServer` and `finish` hooks.
+- Built-in `default` and `docs` themes, plus `xfm create` scaffolding.
+- Dev server with SSE live reload and configuration hot reload.
+- `xfm new`, `xfm build`, `xfm dev`, `xfm clean` commands.
+
+[0.1.1]: https://github.com/xfm0797/xfm/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/xfm0797/xfm/releases/tag/v0.1.0

package/INSTALL.md

@@ -1,81 +1,83 @@
-# xfm 安装与使用说明
+# xfm — Installation & Usage
 
-> 面向 Node 22 环境，从零到跑起来大约 1 分钟。
-> 项目地址：`https://github.com/xfm0797/xfm`
+> Assumes a Node 22 environment. From zero to a running site takes about a minute.
+> Repository: `https://github.com/xfm0797/xfm`
+
+[English](./INSTALL.md) | [简体中文](./INSTALL_CN.md)
 
 ---
 
-## 一、先决条件
+## 1. Prerequisites
 
-| 项目 | 要求 | 检查命令 |
+| Item | Requirement | Check |
 | --- | --- | --- |
-| Node.js | **18 或更高**（推荐 22 LTS） | `node -v` |
-| npm | 随 Node 附带（推荐 ≥ 9） | `npm -v` |
+| Node.js | **18 or newer** (22 LTS recommended) | `node -v` |
+| npm | Ships with Node (>= 9 recommended) | `npm -v` |
 
 ```bash
-node -v    # 期望 v22.x
-npm -v     # 期望 10.x 或 11.x
+node -v    # expect v22.x
+npm -v     # expect 10.x or 11.x
 ```
 
-Node 版本过旧会报 `EBADENGINE`，用 [nvm](https://github.com/nvm-sh/nvm) 或 [fnm](https://github.com/Schniz/fnm) 切到 22 即可：
+An outdated Node version triggers `EBADENGINE`. Switch to 22 with [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm):
 
 ```bash
 nvm install 22 && nvm use 22
 ```
 
-xfm 是**零运行时依赖**的，安装时不会拉取任何第三方包，也因此不会出现依赖树冲突、`npm audit` 报警。
+xfm has **zero runtime dependencies**, so installing it pulls no third-party packages — which also means no dependency-tree conflicts and no `npm audit` warnings.
 
 ---
 
-## 二、安装（三种方式，按需选一种）
+## 2. Install (pick one of three methods)
 
-### 方式 A：全局安装 —— 和 Hexo 一样用 `xfm` 命令
+### Option A: Global install — use `xfm` like you use `hexo`
 
 ```bash
 npm install -g xfmpress
 ```
 
-验证：
+Verify:
 
 ```bash
 xfm --help
 ```
 
-看到 `⚡ xfm v0.1.0` 的版本横幅即安装成功。
+If you see the `⚡ xfm v0.1.0` banner, you are good to go.
 
-> **命名说明**：npm 包名是 **`xfmpress`**，命令是 **`xfm`**（`npm i -g xfmpress` 之后用 `xfm` 调用）。定位是 Static Site Generator（静态站点生成器），与同系列的 `hexo-theme-xfm` 共用品牌。项目早期叫 `bolt`，`bolt`/`bolt-ssg` 已被占用，`xmssg` 与 `xfm` 又分别被 npm 的"名字过于相似"校验拦下（撞 `xss`、以及 `xo`/`xml`/`htm` 等一批短包名），0.1.0 起定为 `xfmpress`。
+> **About the name**: the npm package is **`xfmpress`**, the command is **`xfm`** (`npm i -g xfmpress`, then call `xfm`). It is a Static Site Generator, sharing the `xfm` brand with the `hexo-theme-xfm` family. The project was originally called `bolt`; `bolt`/`bolt-ssg` were taken, and `xmssg` and `xfm` were both rejected by npm's "too similar to an existing package" check (against `xss`, then against `xo`/`xml`/`htm` and friends), so `xfmpress` has been the name since 0.1.0.
 
-**权限报错怎么办**（`EACCES: permission denied`）？有两种正规解法，不要用 `sudo npm i -g`：
+**Hit `EACCES: permission denied`?** There are two proper fixes; do not use `sudo npm i -g`:
 
 ```bash
-# 解法 1（推荐）：把全局前缀改到用户目录
+# Fix 1 (recommended): move the global prefix into your home directory
 npm config set prefix ~/.npm-global
-echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc   # bash 用户改成 ~/.bashrc
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc   # use ~/.bashrc for bash
 source ~/.zshrc
 
-# 解法 2：用 nvm 管理 Node（全局包天然在用户目录，无需额外配置）
+# Fix 2: manage Node with nvm (global packages already live in your home directory)
 ```
 
-### 方式 B：免安装运行 —— 只想先试试
+### Option B: Run without installing — just want to try it
 
 ```bash
 npx xfmpress --help
 npx xfmpress create my-blog --template=blog
 ```
 
-`npx` 会自动下载到临时缓存并执行，不在系统里留下全局命令。适合快速体验或 CI 里一次性构建。
+`npx` downloads into a temporary cache and runs from there, leaving no global command behind. Good for a quick look or a one-off build in CI.
 
-### 方式 C：项目内安装 —— 团队协作推荐
+### Option C: Install into a project — best for teams
 
-把 xfm 作为开发依赖写进项目，任何人 `npm install` 后即可获得**完全一致**的版本：
+Add xfm as a dev dependency so everyone gets the **exact same** version after `npm install`:
 
 ```bash
 mkdir my-blog && cd my-blog
 npm init -y
-npm i -D xfm
+npm i -D xfmpress
 ```
 
-然后在 `package.json` 里加脚本：
+Then add scripts to `package.json`:
 
 ```json
 {
@@ -88,201 +90,207 @@ npm i -D xfm
 }
 ```
 
-之后用 `npm run dev` / `npm run build` 即可；临时调用可用 `npx xfmpress info`。
+From then on use `npm run dev` / `npm run build`; for a one-off command use `npx xfmpress info`.
 
-> 方式 C 的缺点是不能在空目录里用 `xfm create` 生成脚手架（那时还没有 `node_modules`）。建议先用方式 A 或 B 生成站点，再进目录装成本地依赖。
+> The downside of Option C: you cannot run `xfm create` in an empty directory, because there is no `node_modules` yet. Scaffold the site with Option A or B first, then install it locally.
 
 ---
 
-## 三、快速上手
+## 3. Quick start
 
-### 1. 创建站点
+### 1. Create a site
 
 ```bash
 xfm create my-blog --template=blog
 cd my-blog
 ```
 
-可选模板：
+Available templates:
 
-| `--template` | 外观 | 适合 |
+| `--template` | Look | Good for |
 | --- | --- | --- |
-| `blog`（默认） | 博客：首页列表 + 文章页 + 右侧目录 | 个人博客、技术随笔 |
-| `docs` | 文档：左侧分组侧栏 + 正文 | 产品文档、知识库 |
+| `blog` (default) | Blog: post list on the home page, post pages, right-hand TOC | Personal blogs, tech notes |
+| `docs` | Documentation: grouped left sidebar + body | Product docs, knowledge bases |
 
-也能指定站名：
+You can also set the site title:
 
 ```bash
-xfm create my-blog --template=docs --title="我的知识库"
+xfm create my-blog --template=docs --title="My Knowledge Base"
 ```
 
-生成的结构：
+Generated structure:
 
 ```
 my-blog/
-├── xfm.config.mjs      # 站点配置（有合理默认值，可按需改）
-├── content/             # 所有 Markdown 源文件
+├── xfm.config.mjs      # site config (sensible defaults, edit as needed)
+├── content/            # all Markdown sources
 │   ├── index.md
 │   ├── about.md
 │   └── posts/
 │       └── hello-world.md
-├── plugins/             # 你自己的插件
-├── public/              # 原样拷贝到产物根目录的静态文件
+├── plugins/            # your own plugins
+├── public/             # static files copied verbatim to the output root
 └── README.md
 ```
 
-### 2. 本地开发
+### 2. Local development
 
 ```bash
 xfm dev
 ```
 
-打开 `http://127.0.0.1:4000/`。改 `content/` 里的 Markdown 或 `themes/` 里的模板，保存后浏览器**自动刷新**（SSE 推送，无需装浏览器插件）。
+Open `http://127.0.0.1:4173/`. Edit Markdown under `content/` or templates under `themes/`, save, and the browser **refreshes itself** (SSE push, no browser extension needed).
 
 ```bash
-xfm dev --port=5000     # 换端口
+xfm dev --port=5000     # different port
 ```
 
-### 3. 写文章
+### 3. Write a post
 
 ```bash
-xfm new "我的第一篇文章"
-# ✓ 已创建 content/posts/我的第一篇文章.md   （文件名由标题自动转为 slug）
+xfm new "My First Post"
+# ✓ created content/posts/my-first-post.md   (the title is slugified into the filename)
 ```
 
-带空格或多语言的标题会自动处理文件名：
+Titles with spaces or non-ASCII characters are handled automatically:
 
 ```bash
 xfm new "Hello, World!"                  # → content/posts/hello-world.md
-xfm new "部署笔记" --slug=deploy-notes    # → 手动指定文件名
-xfm new "关于" --dir=pages               # → 放到 content/pages/ 下
+xfm new "Deploy notes" --slug=deploy-notes   # → explicit filename
+xfm new "About" --dir=pages              # → under content/pages/
 ```
 
-> **注意**：`xfm new` 生成的文章**默认可发布**，`xfm build` 立刻就能看到。想先写半成品，用 `xfm new --draft`（会写入 `draft: true`），这类文章不会出现在生产构建里；要发布时把 `draft` 改成 `false` 或删掉该行即可。
+> **Note**: posts created by `xfm new` are **publishable by default** and show up on the next `xfm build`. To write a work in progress, use `xfm new --draft` (writes `draft: true`); such posts never appear in production builds. Set `draft` to `false` or delete the line when you are ready to publish.
 
-### 4. 生产构建
+### 4. Production build
 
 ```bash
 xfm build
 ```
 
-产物在 `dist/`，纯静态，扔到 Nginx / 对象存储 / Vercel / Netlify / GitHub Pages 都能跑。
+Output goes to `dist/`, fully static — drop it on Nginx, object storage, Vercel, Netlify or GitHub Pages.
 
 ```
-✓ 页面      5 个
-✓ 附加产物  4 个（sitemap / rss 等）
-✓ 输出目录  dist
-耗时 30 ms
+✓ pages        5
+✓ extra files  4 (sitemap / rss, etc.)
+✓ output       dist
+done in 30 ms
 ```
 
-重构建会走增量缓存，只重新渲染改动过的页面：
+Rebuilds use the incremental cache and only re-render changed pages:
 
 ```bash
-xfm build --dev     # 开发模式下也启用增量缓存
+xfm build --dev     # enable the incremental cache in dev mode too
 ```
 
-### 5. 其他命令
+### 5. Other commands
 
 ```bash
-xfm info        # 查看当前站点解析后的配置（主题、内容目录、插件、Node 版本）
-xfm clean       # 清空 dist/ 与增量缓存
-xfm --help      # 全部命令与选项
+xfm info        # show the resolved config (theme, content dir, plugins, Node version)
+xfm clean       # wipe dist/ and the incremental cache
+xfm --help      # every command and option
 ```
 
 ---
 
-## 四、写 Markdown
+## 4. Writing Markdown
 
-内容就是标准 Markdown，没有私有语法。常用增强：
+Content is plain Markdown — no proprietary syntax. Common extensions:
 
 ````markdown
 ---
-title: 文章标题
+title: Post title
 date: 2024-06-01
-tags: [性能, Node]
-description: 用于 SEO 与列表摘要
+tags: [performance, node]
+description: Used for SEO and list summaries
 layout: post.html
 draft: false
 ---
 
-## 二级标题会自动进右侧目录
+## H2 headings land in the right-hand TOC automatically
 
-普通段落支持 **加粗**、*斜体*、`行内代码`、~~删除线~~、[链接](/about/)。
+Normal paragraphs support **bold**, *italic*, `inline code`, ~~strikethrough~~, [links](/about/).
 
-| 语法 | 说明 |
+| Syntax | Notes |
 | --- | --- |
-| 表格 | 标准 GFM |
+| Tables | Standard GFM |
 
-- [x] 任务列表已支持
-- [ ] 未完成项
+- [x] Task lists work
+- [ ] Unfinished item
 
-::: tip 提示容器
-支持 `tip` / `info` / `warning` / `danger` 四种。
+::: tip Callout
+Four kinds: `tip` / `info` / `warning` / `danger`.
 :::
 
 ```js
-const ok = true; // 代码块自动语法高亮
+const ok = true; // code blocks are highlighted automatically
 ```
 ````
 
-代码高亮支持：`js / javascript / jsx / ts / tsx / java / c / cpp / csharp / go / rust / swift / kotlin / scala / php / python / bash / sh / json / yaml / html / xml / svg / vue / css / scss / markdown`，大小写与常见别名都能识别；未知语言降级为纯文本，不会报错。围栏可加标题：`` ```js app.js ``。
+Highlighting supports: `js / javascript / jsx / ts / tsx / java / c / cpp / csharp / go / rust / swift / kotlin / scala / php / python / bash / sh / json / yaml / html / xml / svg / vue / css / scss / markdown`, case-insensitive and alias-aware; unknown languages degrade to plain text instead of failing. Fences can carry a title: `` ```js app.js ``.
 
 ---
 
-## 五、配置
+## 5. Configuration
 
-`xfm.config.mjs` 是一个普通 ESM 模块，导出对象即可，改动后 dev 服务器会自动重启：
+`xfm.config.mjs` is a plain ESM module — export an object and you are done. The dev server picks up changes automatically:
 
 ```js
 export default {
-  title: '我的博客',
-  description: '记录技术与生活',
-  url: 'https://example.com',      // 用于 sitemap / rss 的绝对链接
-  theme: 'default',                // 内置主题：default | docs；也可填本地路径
+  site: {
+    title: 'My Blog',
+    description: 'Notes on tech and life',
+    url: 'https://example.com',    // absolute links for sitemap / rss
+    lang: 'en',
+    base: '/',
+    nav: [{ title: 'Home', url: '/' }],
+  },
   contentDir: 'content',
-  outputDir: 'dist',
+  outDir: 'dist',
+  theme: 'default',                // built-in: default | docs; or a local path
   plugins: [
     'sitemap',
     'rss',
-    './plugins/my-plugin.js',      // 本地插件
+    './plugins/my-plugin.js',      // local plugin
   ],
-  workers: 0,                      // 0 = 自动；渲染进程数
+  workers: 0,                      // 0 = auto; number of render workers
+  server: { port: 4173 },          // dev port
 };
 ```
 
-所有字段都有默认值，最小配置就是一个空对象。完整字段见 README。
+Every field has a default, so the minimal config is an empty object. Full reference: `README.md` (English) / `README_CN.md` (Chinese).
 
 ---
 
-## 六、常见问题
+## 6. FAQ
 
 **`xfm: command not found`**
-全局 npm 的 `bin` 目录不在 `PATH` 里。执行 `npm bin -g`（旧版）或 `npm config get prefix`，把其下的 `bin` 加进 `PATH`。用 nvm 的话重开一个终端通常就能解决。
+The global npm `bin` directory is not on your `PATH`. Run `npm config get prefix` and add its `bin` subdirectory to `PATH`. With nvm, opening a fresh terminal usually fixes it.
 
-**安装时报 `EACCES: permission denied`**
-见「方式 A」里的全局前缀改法，不要用 `sudo`。
+**`EACCES: permission denied` during install**
+See the global-prefix fix under Option A. Do not use `sudo`.
 
-**`node -v` 低于 18**
-升级 Node 后重装：`npm i -g xfmpress --force`。
+**`node -v` is below 18**
+Upgrade Node, then reinstall: `npm i -g xfmpress --force`.
 
-**`xfm new` 建了文章但页面上没有**
-大概率是 `draft: true`。改成 `false` 后重新 `xfm build`。
+**`xfm new` created a post but it is not on the site**
+Most likely `draft: true`. Change it to `false` and run `xfm build` again.
 
-**Windows 下 `xfm` 提示不是内部或外部命令**
-用 Git Bash 或 PowerShell 重开终端；仍不行则检查 `%APPDATA%\npm` 是否在 `Path` 中。
+**On Windows, `xfm` is "not recognized as an internal or external command"**
+Reopen your terminal in Git Bash or PowerShell. If it still fails, check that `%APPDATA%\npm` is on your `Path`.
 
-**想升级**
+**Upgrading**
 ```bash
-npm i -g xfmpress@latest       # 全局
-npm i -D xfm@latest       # 项目内
+npm i -g xfmpress@latest       # global
+npm i -D xfmpress@latest       # in a project
 ```
 
 ---
 
-## 七、一键脚本（复制即用）
+## 7. One-liner (copy & paste)
 
 ```bash
-# 全局安装 + 创建博客 + 本地预览
+# install globally + scaffold a blog + start the dev server
 npm i -g xfmpress \
   && xfm create my-blog --template=blog \
   && cd my-blog \

package/INSTALL_CN.md

@@ -0,0 +1,298 @@
+# xfm 安装与使用说明
+
+> 面向 Node 22 环境，从零到跑起来大约 1 分钟。
+> 项目地址：`https://github.com/xfm0797/xfm`
+
+[English](./INSTALL.md) | 简体中文
+
+---
+
+## 一、先决条件
+
+| 项目 | 要求 | 检查命令 |
+| --- | --- | --- |
+| Node.js | **18 或更高**（推荐 22 LTS） | `node -v` |
+| npm | 随 Node 附带（推荐 ≥ 9） | `npm -v` |
+
+```bash
+node -v    # 期望 v22.x
+npm -v     # 期望 10.x 或 11.x
+```
+
+Node 版本过旧会报 `EBADENGINE`，用 [nvm](https://github.com/nvm-sh/nvm) 或 [fnm](https://github.com/Schniz/fnm) 切到 22 即可：
+
+```bash
+nvm install 22 && nvm use 22
+```
+
+xfm 是**零运行时依赖**的，安装时不会拉取任何第三方包，也因此不会出现依赖树冲突、`npm audit` 报警。
+
+---
+
+## 二、安装（三种方式，按需选一种）
+
+### 方式 A：全局安装 —— 和 Hexo 一样用 `xfm` 命令
+
+```bash
+npm install -g xfmpress
+```
+
+验证：
+
+```bash
+xfm --help
+```
+
+看到 `⚡ xfm v0.1.0` 的版本横幅即安装成功。
+
+> **命名说明**：npm 包名是 **`xfmpress`**，命令是 **`xfm`**（`npm i -g xfmpress` 之后用 `xfm` 调用）。定位是 Static Site Generator（静态站点生成器），与同系列的 `hexo-theme-xfm` 共用品牌。项目早期叫 `bolt`，`bolt`/`bolt-ssg` 已被占用，`xmssg` 与 `xfm` 又分别被 npm 的"名字过于相似"校验拦下（撞 `xss`、以及 `xo`/`xml`/`htm` 等一批短包名），0.1.0 起定为 `xfmpress`。
+
+**权限报错怎么办**（`EACCES: permission denied`）？有两种正规解法，不要用 `sudo npm i -g`：
+
+```bash
+# 解法 1（推荐）：把全局前缀改到用户目录
+npm config set prefix ~/.npm-global
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc   # bash 用户改成 ~/.bashrc
+source ~/.zshrc
+
+# 解法 2：用 nvm 管理 Node（全局包天然在用户目录，无需额外配置）
+```
+
+### 方式 B：免安装运行 —— 只想先试试
+
+```bash
+npx xfmpress --help
+npx xfmpress create my-blog --template=blog
+```
+
+`npx` 会自动下载到临时缓存并执行，不在系统里留下全局命令。适合快速体验或 CI 里一次性构建。
+
+### 方式 C：项目内安装 —— 团队协作推荐
+
+把 xfm 作为开发依赖写进项目，任何人 `npm install` 后即可获得**完全一致**的版本：
+
+```bash
+mkdir my-blog && cd my-blog
+npm init -y
+npm i -D xfmpress
+```
+
+然后在 `package.json` 里加脚本：
+
+```json
+{
+  "scripts": {
+    "dev": "xfm dev",
+    "build": "xfm build",
+    "new": "xfm new",
+    "clean": "xfm clean"
+  }
+}
+```
+
+之后用 `npm run dev` / `npm run build` 即可；临时调用可用 `npx xfmpress info`。
+
+> 方式 C 的缺点是不能在空目录里用 `xfm create` 生成脚手架（那时还没有 `node_modules`）。建议先用方式 A 或 B 生成站点，再进目录装成本地依赖。
+
+---
+
+## 三、快速上手
+
+### 1. 创建站点
+
+```bash
+xfm create my-blog --template=blog
+cd my-blog
+```
+
+可选模板：
+
+| `--template` | 外观 | 适合 |
+| --- | --- | --- |
+| `blog`（默认） | 博客：首页列表 + 文章页 + 右侧目录 | 个人博客、技术随笔 |
+| `docs` | 文档：左侧分组侧栏 + 正文 | 产品文档、知识库 |
+
+也能指定站名：
+
+```bash
+xfm create my-blog --template=docs --title="我的知识库"
+```
+
+生成的结构：
+
+```
+my-blog/
+├── xfm.config.mjs      # 站点配置（有合理默认值，可按需改）
+├── content/             # 所有 Markdown 源文件
+│   ├── index.md
+│   ├── about.md
+│   └── posts/
+│       └── hello-world.md
+├── plugins/             # 你自己的插件
+├── public/              # 原样拷贝到产物根目录的静态文件
+└── README.md
+```
+
+### 2. 本地开发
+
+```bash
+xfm dev
+```
+
+打开 `http://127.0.0.1:4173/`。改 `content/` 里的 Markdown 或 `themes/` 里的模板，保存后浏览器**自动刷新**（SSE 推送，无需装浏览器插件）。
+
+```bash
+xfm dev --port=5000     # 换端口
+```
+
+### 3. 写文章
+
+```bash
+xfm new "我的第一篇文章"
+# ✓ 已创建 content/posts/我的第一篇文章.md   （文件名由标题自动转为 slug）
+```
+
+带空格或多语言的标题会自动处理文件名：
+
+```bash
+xfm new "Hello, World!"                  # → content/posts/hello-world.md
+xfm new "部署笔记" --slug=deploy-notes    # → 手动指定文件名
+xfm new "关于" --dir=pages               # → 放到 content/pages/ 下
+```
+
+> **注意**：`xfm new` 生成的文章**默认可发布**，`xfm build` 立刻就能看到。想先写半成品，用 `xfm new --draft`（会写入 `draft: true`），这类文章不会出现在生产构建里；要发布时把 `draft` 改成 `false` 或删掉该行即可。
+
+### 4. 生产构建
+
+```bash
+xfm build
+```
+
+产物在 `dist/`，纯静态，扔到 Nginx / 对象存储 / Vercel / Netlify / GitHub Pages 都能跑。
+
+```
+✓ 页面      5 个
+✓ 附加产物  4 个（sitemap / rss 等）
+✓ 输出目录  dist
+耗时 30 ms
+```
+
+重构建会走增量缓存，只重新渲染改动过的页面：
+
+```bash
+xfm build --dev     # 开发模式下也启用增量缓存
+```
+
+### 5. 其他命令
+
+```bash
+xfm info        # 查看当前站点解析后的配置（主题、内容目录、插件、Node 版本）
+xfm clean       # 清空 dist/ 与增量缓存
+xfm --help      # 全部命令与选项
+```
+
+---
+
+## 四、写 Markdown
+
+内容就是标准 Markdown，没有私有语法。常用增强：
+
+````markdown
+---
+title: 文章标题
+date: 2024-06-01
+tags: [性能, Node]
+description: 用于 SEO 与列表摘要
+layout: post.html
+draft: false
+---
+
+## 二级标题会自动进右侧目录
+
+普通段落支持 **加粗**、*斜体*、`行内代码`、~~删除线~~、[链接](/about/)。
+
+| 语法 | 说明 |
+| --- | --- |
+| 表格 | 标准 GFM |
+
+- [x] 任务列表已支持
+- [ ] 未完成项
+
+::: tip 提示容器
+支持 `tip` / `info` / `warning` / `danger` 四种。
+:::
+
+```js
+const ok = true; // 代码块自动语法高亮
+```
+````
+
+代码高亮支持：`js / javascript / jsx / ts / tsx / java / c / cpp / csharp / go / rust / swift / kotlin / scala / php / python / bash / sh / json / yaml / html / xml / svg / vue / css / scss / markdown`，大小写与常见别名都能识别；未知语言降级为纯文本，不会报错。围栏可加标题：`` ```js app.js ``。
+
+---
+
+## 五、配置
+
+`xfm.config.mjs` 是一个普通 ESM 模块，导出对象即可，改动后 dev 服务器会自动重启：
+
+```js
+export default {
+  site: {
+    title: '我的博客',
+    description: '记录技术与生活',
+    url: 'https://example.com',    // 用于 sitemap / rss 的绝对链接
+    lang: 'zh-CN',
+    base: '/',
+    nav: [{ title: '首页', url: '/' }],
+  },
+  contentDir: 'content',
+  outDir: 'dist',
+  theme: 'default',                // 内置主题：default | docs；也可填本地路径
+  plugins: [
+    'sitemap',
+    'rss',
+    './plugins/my-plugin.js',      // 本地插件
+  ],
+  workers: 0,                      // 0 = 自动；渲染进程数
+  server: { port: 4173 },          // dev 端口
+};
+```
+
+所有字段都有默认值，最小配置就是一个空对象。完整字段见 `README_CN.md`（中文）/ `README.md`（English）。
+
+---
+
+## 六、常见问题
+
+**`xfm: command not found`**
+全局 npm 的 `bin` 目录不在 `PATH` 里。执行 `npm bin -g`（旧版）或 `npm config get prefix`，把其下的 `bin` 加进 `PATH`。用 nvm 的话重开一个终端通常就能解决。
+
+**安装时报 `EACCES: permission denied`**
+见「方式 A」里的全局前缀改法，不要用 `sudo`。
+
+**`node -v` 低于 18**
+升级 Node 后重装：`npm i -g xfmpress --force`。
+
+**`xfm new` 建了文章但页面上没有**
+大概率是 `draft: true`。改成 `false` 后重新 `xfm build`。
+
+**Windows 下 `xfm` 提示不是内部或外部命令**
+用 Git Bash 或 PowerShell 重开终端；仍不行则检查 `%APPDATA%\npm` 是否在 `Path` 中。
+
+**想升级**
+```bash
+npm i -g xfmpress@latest       # 全局
+npm i -D xfmpress@latest       # 项目内
+```
+
+---
+
+## 七、一键脚本（复制即用）
+
+```bash
+# 全局安装 + 创建博客 + 本地预览
+npm i -g xfmpress \
+  && xfm create my-blog --template=blog \
+  && cd my-blog \
+  && xfm dev
+```

package/README.md

@@ -1,140 +1,144 @@
 # ⚡ xfm
 
-**A zero-dependency static site generator for Node.js.** 极致性能的静态站点生成器 —— 零运行时依赖、多线程渲染、Nunjucks 风格模板、即插即用的主题与插件。
+**A zero-dependency static site generator for Node.js.** Zero runtime dependencies, multi-threaded rendering, Nunjucks-style templates, drop-in themes and plugins.
 
-## 安装与上手
+[English](./README.md) | [简体中文](./README_CN.md)
+
+## Install & Quick Start
 
 ```bash
-npm i -g xfmpress    # 全局安装（Node ≥ 18），装完命令是 xfm
-xfm create my-blog   # 30 秒创建站点
-cd my-blog && xfm dev   # 毫秒级热更新
-xfm build            # 生产构建
+npm i -g xfmpress    # install globally (Node >= 18); the command is xfm
+xfm create my-blog   # scaffold a site in 30 seconds
+cd my-blog && xfm dev   # instant hot reload
+xfm build            # production build
 ```
 
-> **包名 `xfmpress`，命令 `xfm`**（`npm i -g xfmpress` → 用 `xfm` 调用）。定位是 **Static Site Generator（静态站点生成器）**：把 Markdown 压成纯静态 HTML。
-> 与同系列的 [hexo-theme-xfm](https://github.com/xfm0797/hexo-theme-xfm) 共用 `xfm` 品牌。
-> 完整的三种安装方式、权限排错与 FAQ 见 **[INSTALL.md](./INSTALL.md)**。
+> **Package name `xfmpress`, command `xfm`** (`npm i -g xfmpress`, then call `xfm`).
+> This is a **static site generator**: it compresses Markdown into plain static HTML.
+> Shares the `xfm` brand with [hexo-theme-xfm](https://github.com/xfm0797/hexo-theme-xfm).
+> All three install methods, permission troubleshooting and the FAQ live in **[INSTALL.md](./INSTALL.md)**.
 
-## 性能
+## Performance
 
-压测环境：32 核 Node 22，1000 篇中文文档（约 5MB HTML 产出）。运行 `npm run bench` 可复现。
+Benchmark: 32-core machine, Node 22, 1,000 Chinese documents (~5 MB of HTML output). Reproduce with `npm run bench`.
 
-| 指标 | 数值 |
+| Metric | Value |
 | --- | --- |
-| 全量冷构建 | **≈0.38–0.42 s**（≈2400–2700 页/秒） |
-| 增量缓存命中后渲染阶段 | **1 ms**（1001 页） |
-| dev 热更新单页重建 | **2–7 ms** |
-| 产物运行时 | 纯静态 HTML + CSS，**零 JavaScript 依赖** |
+| Full cold build | **≈0.38–0.42 s** (≈2,400–2,700 pages/s) |
+| Render phase with warm cache | **1 ms** (1,001 pages) |
+| Dev hot rebuild of a single page | **2–7 ms** |
+| Runtime footprint | plain static HTML + CSS, **zero JavaScript** |
 
-分阶段耗时（1000 页）：
+Per-stage timing (1,000 pages):
 
-| 阶段 | 耗时 | 优化手段 |
+| Stage | Time | How |
 | --- | --- | --- |
-| 扫描与解析 | ~128 ms | 目录并行遍历 + 源文件并行读取，raw 只读一次 |
-| 哈希 | ~9 ms | 复用已读入的源文本，无二次 IO |
-| 渲染 | ~91 ms | worker 池复用线程，上下文只传一次 |
-| 写盘 | ~132 ms | 同目录只 mkdir 一次，两阶段并行写 |
+| Scan & parse | ~128 ms | Parallel directory walk + parallel source reads; each file is read once |
+| Hashing | ~9 ms | Reuses the already-read source text, no second IO |
+| Render | ~91 ms | Worker pool reuses threads; site context is serialized once |
+| Write | ~132 ms | One `mkdir` per directory, two-phase parallel writes |
 
-性能来自四层设计：
+Four design decisions carry the performance:
 
-1. **线性扫描的 Markdown 引擎**：块级逐行推进 + 一次性行内正则，不构造 AST；内置中英文锚点、表格、任务列表（含续行与嵌套）、代码高亮、`::: callout` 容器。
-2. **模板编译成函数**：Nunjucks 风格语法在构建期编译为 JS 函数，渲染只做字符串拼接，未定义变量安全返回 undefined。
-3. **worker 池**：线程与模板编译缓存全程复用，站点上下文只序列化一次；并发度按"每线程最少工作量"标定（实测 2–4 个最优，堆到 8 个反而更慢）。
-4. **增量构建**：`源文件哈希 + 主题指纹` 判定，未变页面直接复用缓存 HTML。
+1. **Line-scanning Markdown engine**: advances line by line at block level plus a single inline regex pass, no AST. Ships CJK and English anchors, tables, task lists (with continuation lines and nesting), syntax highlighting and `::: callout` containers.
+2. **Templates compiled to functions**: Nunjucks-style syntax is compiled into plain JS functions at build time, so rendering is string concatenation; undefined variables resolve safely to `undefined`.
+3. **Worker pool**: threads and template compile caches are reused for the whole run, and the site context is serialized only once. Concurrency is calibrated by *minimum work per thread* — 2–4 threads measured fastest; forcing 8 is actually slower.
+4. **Incremental builds**: a page is reused from cache when `source hash + theme fingerprint` are unchanged.
 
-> 并发度不是越多越好：worker 的启动与上下文克隆成本约 30–60 ms/个，
-> 在小任务量下会吃掉并行收益。`pickConcurrency()` 依据实测数据标定，而非按 CPU 核数堆线程。
+> More workers is not better: spinning up a worker and cloning the context costs ~30–60 ms each,
+> which eats the parallel gain on small workloads. `pickConcurrency()` calibrates from measurements
+> instead of blindly matching CPU core count.
 
-## 特性
+## Features
 
-- **主题**：`{% extend %}` / `{% block %}` 模板继承、`{% include %}` 片段、CSS 变量深浅色主题；内置 `default`（博客）与 `docs`（侧栏文档）两套主题。
-- **插件**：五个钩子（`extendContext` / `markdown` / `transformHtml` / `afterBuild` / `configureServer`），放进 `plugins/` 目录自动加载；内置 sitemap、RSS、阅读统计三个插件。
-- **内容**：YAML front-matter、草稿、标签/分类/系列聚合、自动 prev/next、按 weight 排序、`.md` 相对链接自动解析。
-- **开发体验**：`xfm dev` 内存构建 + SSE 热更新（保持滚动位置）、CSS 单独热替换、404 页列出可用路由。
-- **易迁移**：模板语法兼容 Nunjucks/Liquid 习惯，配置文件支持 `.mjs/.js/.json`。
+- **Themes**: `{% extend %}` / `{% block %}` template inheritance, `{% include %}` partials, CSS-variable light/dark themes. Ships `default` (blog) and `docs` (sidebar documentation).
+- **Plugins**: five hooks (`extendContext` / `markdown` / `transformHtml` / `afterBuild` / `configureServer`); drop a file into `plugins/` and it loads itself. Ships sitemap, RSS and reading-stats.
+- **Content**: YAML front-matter, drafts, tag/category/series taxonomies, automatic prev/next, `weight` ordering, and relative `.md` links resolved automatically.
+- **Developer experience**: `xfm dev` builds in memory with SSE hot reload (keeps your scroll position), hot-swaps CSS separately, and lists available routes on 404.
+- **Easy to migrate**: template syntax follows Nunjucks/Liquid conventions; config supports `.mjs/.js/.json`.
 
-## 安装
+## Install
 
 ```bash
-npm i -g xfmpress      # 全局安装，然后直接使用 xfm 命令（Node ≥ 18）
-# 或免安装试用：npx xfmpress --help
+npm i -g xfmpress      # then use the xfm command (Node >= 18)
+# or try without installing: npx xfmpress --help
 ```
 
-> 包名是 `xfmpress`，命令是 `xfm`，装一次即可全局使用。
-> 完整的安装、权限排错与三种安装方式见 **[INSTALL.md](./INSTALL.md)**。
+> The package is `xfmpress`, the command is `xfm` — install once, use anywhere.
+> Full install guide, permission troubleshooting and three install methods: **[INSTALL.md](./INSTALL.md)**.
 
-## 命令
+## Commands
 
-| 命令 | 说明 |
+| Command | Description |
 | --- | --- |
-| `xfm create [目录]` | 创建站点（`--template=blog\|docs`，`--title=`） |
-| `xfm dev [目录]` | 开发服务器（`--port=`） |
-| `xfm build [目录]` | 生产构建（`--dev` 启用增量缓存） |
-| `xfm new "标题"` | 新建文章（`--dir=posts --slug=xxx`） |
-| `xfm clean` / `xfm info` | 清理产物 / 查看配置 |
+| `xfm create [dir]` | Scaffold a site (`--template=blog\|docs`, `--title=`) |
+| `xfm dev [dir]` | Dev server (`--port=`) |
+| `xfm build [dir]` | Production build (`--dev` enables incremental cache) |
+| `xfm new "Title"` | New post (`--dir=posts --slug=xxx --draft`) |
+| `xfm clean` / `xfm info` | Clean output / show config |
 
-## 配置示例（xfm.config.mjs）
+## Configuration (`xfm.config.mjs`)
 
 ```js
 export default {
   site: {
     title: 'XFM Notes',
-    description: '关于静态站点与前端的笔记',
-    lang: 'zh-CN',
+    description: 'Notes on static sites and the frontend',
+    lang: 'en',
     base: '/',
-    url: 'https://example.com',      // 供 sitemap/RSS 使用
-    nav: [{ title: '文章', url: '/' }],
+    url: 'https://example.com',      // used by sitemap/RSS
+    nav: [{ title: 'Posts', url: '/' }],
   },
-  theme: 'default',                  // 主题名或路径
-  plugins: ['sitemap', 'rss'],       // 内置插件，也可写路径
+  theme: 'default',                  // theme name or path
+  plugins: ['sitemap', 'rss'],       // built-in names or paths
   defaults: { layout: 'post.html' },
-  workers: 0,                        // worker 并发数；0=自动按任务量标定
-  server: { port: 4321 },
+  workers: 0,                        // worker count; 0 = auto-calibrated
+  server: { port: 4173 },
 };
 ```
 
-## 写作（content/ 目录）
+## Writing (`content/`)
 
 ```markdown
 ---
-title: 文章标题
+title: Post title
 date: 2026-10-28 09:00:00
-tags: [Node.js, 性能]
-description: 摘要（列表页与 RSS 使用）
+tags: [nodejs, performance]
+description: Summary (used by list pages and RSS)
 draft: false
 ---
 
-正文支持 GFM 全部常用语法，另加：
+Body supports the common GFM syntax, plus:
 
-::: tip 提示容器
-带标题的高亮提示框。
+::: tip Callout
+A highlighted box with a title.
 :::
 
 \`\`\`js
-const ok = true; // 内置语法高亮
+const ok = true; // built-in syntax highlighting
 \`\`\`
 
-代码围栏语言标记（含别名归一，大小写不敏感）：`js / javascript / jsx / ts / tsx / java / c / cpp / csharp / go / golang / rust / rs / swift / kotlin / scala / php / python / py / bash / sh / shell / json / yaml / yml / html / xml / svg / vue / css / scss / markdown / md / text`。未知语言降级为纯转义文本，不会报错。
+Fence languages (aliases normalized, case-insensitive): `js / javascript / jsx / ts / tsx / java / c / cpp / csharp / go / golang / rust / rs / swift / kotlin / scala / php / python / py / bash / sh / shell / json / yaml / yml / html / xml / svg / vue / css / scss / markdown / md / text`. Unknown languages fall back to escaped plain text instead of failing.
 
-围栏首行可附加标题：\`\`\`js app.js（元信息如 `{1,3-5}` 会被忽略）。
+A fence can carry a title on its first line: \`\`\`js app.js (meta such as `{1,3-5}` is ignored).
 ```
 
-`group: 使用指南` + `weight: 1` 字段可在 docs 主题生成侧栏导航。
+In the `docs` theme, `group: Getting Started` plus `weight: 1` builds the sidebar navigation.
 
-## 钩子语义
+## Hook semantics
 
-| 钩子 | 参数 | 返回值处理 |
+| Hook | Arguments | Return value |
 | --- | --- | --- |
-| `extendContext(ctx)` | 站点上下文 | 替换上下文（返回值写入 `site.*`） |
-| `markdown(src, page)` | 当前源码 | 替换源码 |
-| `transformHtml(html, ctx)` | 当前 HTML | 替换 HTML |
-| `afterBuild(site)` | 站点实例（`site.documents[].html` 为**正文** HTML，不含布局） | 返回的 `[{path, contents}]` 被汇总写出 |
-| `configureServer(server)` / `finish(site)` | 站点/服务器 | 忽略 |
+| `extendContext(ctx)` | Site context | Replaces the context (merged into `site.*`) |
+| `markdown(src, page)` | Current source | Replaces the source |
+| `transformHtml(html, ctx)` | Current HTML | Replaces the HTML |
+| `afterBuild(site)` | Site instance (`site.documents[].html` is **body** HTML, without layout) | Returned `[{path, contents}]` are written out |
+| `configureServer(server)` / `finish(site)` | Site / server | Ignored |
 
-## 插件示例
+## Plugin example
 
 ```js
-// plugins/search-index.js —— 放进 plugins/ 目录即生效
+// plugins/search-index.js — drop into plugins/ and it runs
 module.exports = () => ({
   name: 'search-index',
   afterBuild(site) {
@@ -147,39 +151,39 @@ module.exports = () => ({
 });
 ```
 
-## 主题结构
+## Theme structure
 
 ```
 themes/my-theme/
-├── layouts/        # base.html（骨架）、index/post/page.html（继承 base）
-├── partials/       # 可复用片段（toc、卡片等）
-└── assets/         # style.css 等，构建时复制到站点 /assets/
+├── layouts/        # base.html (skeleton), index/post/page.html (extend base)
+├── partials/       # reusable fragments (toc, cards, ...)
+└── assets/         # style.css and friends, copied to /assets/ on build
 ```
 
-模板上下文：`site.*`（站点配置与聚合数据）、`page.*`（当前页元数据）、`content`（正文 HTML）、`headings`（目录）。
+Template context: `site.*` (site config and aggregated data), `page.*` (current page metadata), `content` (body HTML), `headings` (table of contents).
 
-## 目录
+## Project layout
 
 ```
 xfm/
-├── bin/xfm.js         # CLI（build/dev/new/create/clean/info）
+├── bin/xfm.js         # CLI (build/dev/new/create/clean/info)
 ├── lib/engine/         # markdown / template / render / frontmatter / theme / plugins / site / worker / server / config
-├── lib/plugins/        # 内置插件（sitemap / rss / reading-stats）
-├── lib/cli/scaffold.js # create 脚手架
-├── themes/default/     # 博客主题（深浅色）
-├── themes/docs/        # 文档主题（侧栏导航）
-├── examples/blog/      # 可构建的示例站点
-├── bench/bench.js      # 基准测试（分阶段耗时）
-└── test/run.js         # 72 项测试（零依赖）
+├── lib/plugins/        # built-in plugins (sitemap / rss / reading-stats)
+├── lib/cli/scaffold.js # create scaffolding
+├── themes/default/     # blog theme (light/dark)
+├── themes/docs/        # docs theme (sidebar navigation)
+├── examples/blog/      # buildable example site
+├── bench/bench.js      # benchmark (per-stage timings)
+└── test/run.js         # 72 tests (zero dependencies)
 ```
 
-## 本地开发
+## Local development
 
 ```bash
-npm run test           # 72 项测试
-npm run bench          # 1000 页基准（分阶段耗时）
-npm run build:example  # 构建示例站点
-npm run dev            # 开发示例站点
+npm run test           # 72 tests
+npm run bench          # 1,000-page benchmark (per-stage timings)
+npm run build:example  # build the example site
+npm run dev            # dev-server the example site
 ```
 
 MIT License

package/README_CN.md

@@ -0,0 +1,187 @@
+# ⚡ xfm
+
+**A zero-dependency static site generator for Node.js.** 极致性能的静态站点生成器 —— 零运行时依赖、多线程渲染、Nunjucks 风格模板、即插即用的主题与插件。
+
+[English](./README.md) | 简体中文
+
+## 安装与上手
+
+```bash
+npm i -g xfmpress    # 全局安装（Node ≥ 18），装完命令是 xfm
+xfm create my-blog   # 30 秒创建站点
+cd my-blog && xfm dev   # 毫秒级热更新
+xfm build            # 生产构建
+```
+
+> **包名 `xfmpress`，命令 `xfm`**（`npm i -g xfmpress` → 用 `xfm` 调用）。定位是 **Static Site Generator（静态站点生成器）**：把 Markdown 压成纯静态 HTML。
+> 与同系列的 [hexo-theme-xfm](https://github.com/xfm0797/hexo-theme-xfm) 共用 `xfm` 品牌。
+> 完整的三种安装方式、权限排错与 FAQ 见 **[INSTALL_CN.md](./INSTALL_CN.md)**。
+
+## 性能
+
+压测环境：32 核 Node 22，1000 篇中文文档（约 5MB HTML 产出）。运行 `npm run bench` 可复现。
+
+| 指标 | 数值 |
+| --- | --- |
+| 全量冷构建 | **≈0.38–0.42 s**（≈2400–2700 页/秒） |
+| 增量缓存命中后渲染阶段 | **1 ms**（1001 页） |
+| dev 热更新单页重建 | **2–7 ms** |
+| 产物运行时 | 纯静态 HTML + CSS，**零 JavaScript 依赖** |
+
+分阶段耗时（1000 页）：
+
+| 阶段 | 耗时 | 优化手段 |
+| --- | --- | --- |
+| 扫描与解析 | ~128 ms | 目录并行遍历 + 源文件并行读取，raw 只读一次 |
+| 哈希 | ~9 ms | 复用已读入的源文本，无二次 IO |
+| 渲染 | ~91 ms | worker 池复用线程，上下文只传一次 |
+| 写盘 | ~132 ms | 同目录只 mkdir 一次，两阶段并行写 |
+
+性能来自四层设计：
+
+1. **线性扫描的 Markdown 引擎**：块级逐行推进 + 一次性行内正则，不构造 AST；内置中英文锚点、表格、任务列表（含续行与嵌套）、代码高亮、`::: callout` 容器。
+2. **模板编译成函数**：Nunjucks 风格语法在构建期编译为 JS 函数，渲染只做字符串拼接，未定义变量安全返回 undefined。
+3. **worker 池**：线程与模板编译缓存全程复用，站点上下文只序列化一次；并发度按"每线程最少工作量"标定（实测 2–4 个最优，堆到 8 个反而更慢）。
+4. **增量构建**：`源文件哈希 + 主题指纹` 判定，未变页面直接复用缓存 HTML。
+
+> 并发度不是越多越好：worker 的启动与上下文克隆成本约 30–60 ms/个，
+> 在小任务量下会吃掉并行收益。`pickConcurrency()` 依据实测数据标定，而非按 CPU 核数堆线程。
+
+## 特性
+
+- **主题**：`{% extend %}` / `{% block %}` 模板继承、`{% include %}` 片段、CSS 变量深浅色主题；内置 `default`（博客）与 `docs`（侧栏文档）两套主题。
+- **插件**：五个钩子（`extendContext` / `markdown` / `transformHtml` / `afterBuild` / `configureServer`），放进 `plugins/` 目录自动加载；内置 sitemap、RSS、阅读统计三个插件。
+- **内容**：YAML front-matter、草稿、标签/分类/系列聚合、自动 prev/next、按 weight 排序、`.md` 相对链接自动解析。
+- **开发体验**：`xfm dev` 内存构建 + SSE 热更新（保持滚动位置）、CSS 单独热替换、404 页列出可用路由。
+- **易迁移**：模板语法兼容 Nunjucks/Liquid 习惯，配置文件支持 `.mjs/.js/.json`。
+
+## 安装
+
+```bash
+npm i -g xfmpress      # 全局安装，然后直接使用 xfm 命令（Node ≥ 18）
+# 或免安装试用：npx xfmpress --help
+```
+
+> 包名是 `xfmpress`，命令是 `xfm`，装一次即可全局使用。
+> 完整的安装、权限排错与三种安装方式见 **[INSTALL_CN.md](./INSTALL_CN.md)**。
+
+## 命令
+
+| 命令 | 说明 |
+| --- | --- |
+| `xfm create [目录]` | 创建站点（`--template=blog\|docs`，`--title=`） |
+| `xfm dev [目录]` | 开发服务器（`--port=`） |
+| `xfm build [目录]` | 生产构建（`--dev` 启用增量缓存） |
+| `xfm new "标题"` | 新建文章（`--dir=posts --slug=xxx`） |
+| `xfm clean` / `xfm info` | 清理产物 / 查看配置 |
+
+## 配置示例（xfm.config.mjs）
+
+```js
+export default {
+  site: {
+    title: 'XFM Notes',
+    description: '关于静态站点与前端的笔记',
+    lang: 'zh-CN',
+    base: '/',
+    url: 'https://example.com',      // 供 sitemap/RSS 使用
+    nav: [{ title: '文章', url: '/' }],
+  },
+  theme: 'default',                  // 主题名或路径
+  plugins: ['sitemap', 'rss'],       // 内置插件，也可写路径
+  defaults: { layout: 'post.html' },
+  workers: 0,                        // worker 并发数；0=自动按任务量标定
+  server: { port: 4173 },
+};
+```
+
+## 写作（content/ 目录）
+
+```markdown
+---
+title: 文章标题
+date: 2026-10-28 09:00:00
+tags: [Node.js, 性能]
+description: 摘要（列表页与 RSS 使用）
+draft: false
+---
+
+正文支持 GFM 全部常用语法，另加：
+
+::: tip 提示容器
+带标题的高亮提示框。
+:::
+
+\`\`\`js
+const ok = true; // 内置语法高亮
+\`\`\`
+
+代码围栏语言标记（含别名归一，大小写不敏感）：`js / javascript / jsx / ts / tsx / java / c / cpp / csharp / go / golang / rust / rs / swift / kotlin / scala / php / python / py / bash / sh / shell / json / yaml / yml / html / xml / svg / vue / css / scss / markdown / md / text`。未知语言降级为纯转义文本，不会报错。
+
+围栏首行可附加标题：\`\`\`js app.js（元信息如 `{1,3-5}` 会被忽略）。
+```
+
+`group: 使用指南` + `weight: 1` 字段可在 docs 主题生成侧栏导航。
+
+## 钩子语义
+
+| 钩子 | 参数 | 返回值处理 |
+| --- | --- | --- |
+| `extendContext(ctx)` | 站点上下文 | 替换上下文（返回值写入 `site.*`） |
+| `markdown(src, page)` | 当前源码 | 替换源码 |
+| `transformHtml(html, ctx)` | 当前 HTML | 替换 HTML |
+| `afterBuild(site)` | 站点实例（`site.documents[].html` 为**正文** HTML，不含布局） | 返回的 `[{path, contents}]` 被汇总写出 |
+| `configureServer(server)` / `finish(site)` | 站点/服务器 | 忽略 |
+
+## 插件示例
+
+```js
+// plugins/search-index.js —— 放进 plugins/ 目录即生效
+module.exports = () => ({
+  name: 'search-index',
+  afterBuild(site) {
+    const index = site.documents.map(d => ({
+      title: d.title, url: d.url,
+      text: d.html.replace(/<[^>]+>/g, ' ').slice(0, 800),
+    }));
+    return [{ path: 'search.json', contents: JSON.stringify(index) }];
+  },
+});
+```
+
+## 主题结构
+
+```
+themes/my-theme/
+├── layouts/        # base.html（骨架）、index/post/page.html（继承 base）
+├── partials/       # 可复用片段（toc、卡片等）
+└── assets/         # style.css 等，构建时复制到站点 /assets/
+```
+
+模板上下文：`site.*`（站点配置与聚合数据）、`page.*`（当前页元数据）、`content`（正文 HTML）、`headings`（目录）。
+
+## 目录
+
+```
+xfm/
+├── bin/xfm.js         # CLI（build/dev/new/create/clean/info）
+├── lib/engine/         # markdown / template / render / frontmatter / theme / plugins / site / worker / server / config
+├── lib/plugins/        # 内置插件（sitemap / rss / reading-stats）
+├── lib/cli/scaffold.js # create 脚手架
+├── themes/default/     # 博客主题（深浅色）
+├── themes/docs/        # 文档主题（侧栏导航）
+├── examples/blog/      # 可构建的示例站点
+├── bench/bench.js      # 基准测试（分阶段耗时）
+└── test/run.js         # 72 项测试（零依赖）
+```
+
+## 本地开发
+
+```bash
+npm run test           # 72 项测试
+npm run bench          # 1000 页基准（分阶段耗时）
+npm run build:example  # 构建示例站点
+npm run dev            # 开发示例站点
+```
+
+MIT License

package/bin/xfm.js

@@ -253,7 +253,7 @@ ${paint(C.bold, '命令')}
   info [目录]          查看站点配置
 
 ${paint(C.bold, '选项')}
-  --port=4000          dev 端口
+  --port=4173          dev 端口（默认 4173）
   --dev                build 时启用增量缓存
   --template=docs      create 时使用文档模板
   --draft              new 时生成草稿（默认直接可发布）

package/lib/cli/scaffold.js

@@ -43,7 +43,7 @@ async function scaffold(args) {
   theme: '${template === 'docs' ? 'docs' : 'default'}',
   plugins: ['sitemap', 'rss'],
   defaults: { layout: '${layout}' },
-  server: { port: 4321 },
+  server: { port: 4173 },
 };
 `
   );

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "xfmpress",
-  "version": "0.1.0",
-  "description": "Zero-dependency static site generator for Node.js — 极致性能、多线程渲染、主题与插件系统",
+  "version": "0.1.1",
+  "description": "Zero-dependency static site generator for Node.js — multi-threaded rendering, Nunjucks-style templates, drop-in themes and plugins",
   "bin": {
     "xfm": "bin/xfm.js"
   },
@@ -14,7 +14,10 @@
     "bin",
     "lib",
     "themes",
-    "INSTALL.md"
+    "INSTALL.md",
+    "README_CN.md",
+    "INSTALL_CN.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "test": "node test/run.js",