实用对比：安装、预览、部署与扩展

本页比较开发者需要实际操作的命令和文件，不把一次 benchmark 运行变成普遍排名。表中的命令来自各项目官方文档；Pagekiln 命令以本仓库当前 CLI 为准。

最短可运行路径

工具	安装 / 启动	本地预览	生产构建	扩展入口
Pagekiln	`npm install`；`npm link`；`pagekiln init`	`pagekiln s`	`pagekiln g` → `dist/`	`themes/<name>/theme.ts`、`theme.yml`、`style.css`、插件开关
Astro	`npm create astro@latest`	`npm run dev`	`npm run build` → `dist/`	`.astro` 页面、组件、integrations
Eleventy	`npm install @11ty/eleventy`；`npx @11ty/eleventy --serve`	`npx @11ty/eleventy --serve`	`npx @11ty/eleventy` → `_site/`	模板、shortcodes、Data Cascade
Hugo	安装 Hugo；`hugo new site`	`hugo server`	`hugo` → `public/`	`layouts/`、shortcodes、modules、resources
VitePress	`npx vitepress init`	`npm run docs:dev`	`npm run docs:build` → `.vitepress/dist/`	Vue 主题、Markdown 中的 Vue 组件
Docusaurus	`npm init docusaurus@latest my-website classic`	`npm run start`	`npm run build` → `build/`	React 主题、plugins、MDX

输出目录是部署事实，不是外观细节：托管平台必须发布构建命令产生的目录。Pagekiln 当前统一静态目录是 dist/，部署命令从 config.yml 读取目的地。

Pagekiln 任务配方

安装新站点

npm install
npm link
pagekiln init
pagekiln check

Starter 是真实源码目录。它的 config.yml、content/ 和 themes/ 展示 CLI 复制的契约。

预览并编辑

pagekiln s
pagekiln s --port=4174

预览服务监听 config.yml、content/ 和 themes/。Markdown、CSS 或主题编辑会触发重建和浏览器刷新，诊断错误后进程仍然保持运行。

部署

deployment:
  targets: [cloudflare-pages, github-pages, vps]
  cloudflare:
    apiTokenEnv: CLOUDFLARE_API_TOKEN
    pages:
      project: example-site
      branch: production
  github:
    remote: origin
    branch: gh-pages
    tokenEnv: GITHUB_TOKEN
  vps:
    host: vps.example.com
    user: deploy
    port: 22
    remotePath: /var/www/example-site
    identityFile: ~/.ssh/id_ed25519

pagekiln d --dry-run
pagekiln d

支持的 connector 是 cloudflare-pages、cloudflare-workers、github-pages、vps 和可选的 openai-sites handoff。Token 放在环境变量中。VPS 使用本机 SSH agent 或已有私钥认证，服务器必须已经授权对应公钥。纯静态托管不需要动态 backend。

开发 Block

content/pages/guide/zh-sg.md   当前说明
themes/default/theme.ts        Block 渲染器和 schema
themes/default/theme.yml       Block/资源注册
themes/default/style.css       单一视觉来源

通过 defineTheme 实现 Block，在 theme.yml 注册，用 Markdown 指令调用，再运行：

npm run compile-theme
pagekiln catalog
pagekiln inspect block:notice
pagekiln check
pagekiln g

完整示例和安全边界见二次开发。

各工具需要维护什么

Pagekiln

内容身份明确：content/pages/<id>/<locale>.md 是当前站点内容，content/posts/<id>/<locale>.md 是带必填 date 的产品笔记。docs 是 pages 内的 Pattern，不是并列 collection。config.yml 负责站点设置和部署目的地；复制的主题负责 Pattern、Block、CSS、浏览器 ESM 和插件呈现。

Astro

Astro官方安装文档从 npm create astro@latest 开始；开发与构建文档使用 npm run dev 和 npm run build。.astro 页面、组件、integrations 和 content collections 构成扩展面。需要组件和 integrations 作为主要开发方式时，使用这条路径。

Eleventy

Eleventy官网展示 Markdown、模板、npx @11ty/eleventy --serve 和 _site/；Data Cascade与Collections是主要组织面。需要多种模板语言和数据组合时，使用这条路径。

Hugo

Hugo快速开始使用 hugo new site、hugo server 和 hugo，输出为 public/；内容组织和shortcodes把结构放进内容树和布局。需要 sections、taxonomies、模板和原生二进制时，使用这条路径。

VitePress

VitePress入门文档使用 npx vitepress init、npm run docs:dev 和 npm run docs:build；在 Markdown 中使用 Vue让 Vue 组件和客户端行为成为文档创作的一部分。文档站本身就是 Vue 应用时，使用这条路径。

Docusaurus

Docusaurus安装文档使用 React starter、npm run start 和 npm run build；i18n 文档处理 locale 目录以及主题和插件翻译。需要 docs sidebar、版本、MDX 和 React plugins 时，使用这条路径。

按下一个具体任务选择

需要 Markdown 优先的产品站，并且要明确区分当前页面、带日期产品笔记、语言、搜索、归档、sitemap 和静态部署：使用 Pagekiln，从 Guide 开始。
需要 .astro 组件或 integrations 生态：使用 Astro starter。
需要模板语言选择和 Data Cascade：使用 Eleventy starter。
需要 sections、taxonomies、shortcodes 和原生二进制：使用 Hugo 快速开始。
需要在文档中使用 Vue 组件：使用 VitePress。
需要带 sidebar、版本和插件翻译的 React/MDX 文档：使用 Docusaurus。

选择应跟随下一个需要编写的文件。对 Pagekiln 来说，当前用法写入 content/pages/，有日期的变化写入 content/posts/，新 Block 写入 themes/<name>/theme.ts。