xfmpress 0.0.0-stage → 0.1.0

package/INSTALL.md

@@ -0,0 +1,290 @@
+# xfm 安装与使用说明
+
+> 面向 Node 22 环境，从零到跑起来大约 1 分钟。
+> 项目地址：`https://github.com/xfm0797/xfm`
+
+---
+
+## 一、先决条件
+
+| 项目 | 要求 | 检查命令 |
+| --- | --- | --- |
+| 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 xfm
+```
+
+然后在 `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:4000/`。改 `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 {
+  title: '我的博客',
+  description: '记录技术与生活',
+  url: 'https://example.com',      // 用于 sitemap / rss 的绝对链接
+  theme: 'default',                // 内置主题：default | docs；也可填本地路径
+  contentDir: 'content',
+  outputDir: 'dist',
+  plugins: [
+    'sitemap',
+    'rss',
+    './plugins/my-plugin.js',      // 本地插件
+  ],
+  workers: 0,                      // 0 = 自动；渲染进程数
+};
+```
+
+所有字段都有默认值，最小配置就是一个空对象。完整字段见 README。
+
+---
+
+## 六、常见问题
+
+**`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 xfm@latest       # 项目内
+```
+
+---
+
+## 七、一键脚本（复制即用）
+
+```bash
+# 全局安装 + 创建博客 + 本地预览
+npm i -g xfmpress \
+  && xfm create my-blog --template=blog \
+  && cd my-blog \
+  && xfm dev
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xfm contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,185 @@
-# Temporary Holding Version
+# ⚡ xfm
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A zero-dependency static site generator for Node.js.** 极致性能的静态站点生成器 —— 零运行时依赖、多线程渲染、Nunjucks 风格模板、即插即用的主题与插件。
+
+## 安装与上手
+
+```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.md](./INSTALL.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.md](./INSTALL.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: 4321 },
+};
+```
+
+## 写作（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