Require Jekyll for local docs preview

Author: maikebing

Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gem 'github-pages', group: :jekyll_plugins

README.md

@@ -15,7 +15,7 @@
 - CI 文档：`docs/ci-workflows.md`
 - 英文 CI 文档：`docs/ci-workflows.en.md`
 - 中文导航：`docs/navigation.md`
-- 英文导航：`docs/navigation.en.md` 
+- 英文导航：`docs/navigation.en.md`
 - 中文博客索引：`docs/blog/index.md`
 - 英文博客索引：`docs/blog/index.en.md`
 
@@ -26,6 +26,8 @@
 
 本地预览建议：
 
+- 本地预览基于 Jekyll，与 GitHub Pages 保持一致。
+- 首次使用前，请先安装 Ruby 与 Bundler，并在仓库根目录执行 `bundle install`。
 - 可运行 `preview/preview-pages.ps1` 在本地生成并预览 Pages HTML。
 - 默认地址为 `http://127.0.0.1:4000/`。
 - 如只想生成 `_site` 而不启动预览，可使用 `preview/preview-pages.ps1 -NoServe`。

preview/preview-pages.ps1

@@ -58,13 +58,22 @@ if (Test-Path (Join-Path $repoRoot 'docs\images')) {
 Push-Location $repoRoot
 try {
     $bundle = Get-Command bundle -ErrorAction SilentlyContinue
-    if ($bundle) {
-        Write-Host 'Building site with Jekyll (bundle exec jekyll build)...' -ForegroundColor Cyan
-        & bundle exec jekyll build --source $pagesSrc --destination $siteDir
+    if (-not $bundle) {
+        throw "未找到 Bundler。请先安装 Ruby + Bundler，并在仓库根目录执行：bundle install"
     }
-    else {
-        Write-Warning 'Ruby/Bundler 未安装，改用 GitHub Pages 等效的静态预览方式：直接复制 Markdown 源到 _site。此模式仅用于快速查看文件结构，不会生成最终 HTML。'
-        Copy-Item (Join-Path $pagesSrc '*') $siteDir -Recurse -Force
+
+    Write-Host 'Checking Jekyll/GitHub Pages dependencies...' -ForegroundColor Cyan
+    & bundle exec jekyll --version | Out-Host
+
+    if ($LASTEXITCODE -ne 0) {
+        throw "Jekyll 不可用。请先在仓库根目录执行：bundle install"
+    }
+
+    Write-Host 'Building site with Jekyll (bundle exec jekyll build)...' -ForegroundColor Cyan
+    & bundle exec jekyll build --source $pagesSrc --destination $siteDir
+
+    if ($LASTEXITCODE -ne 0) {
+        throw "Jekyll 构建失败，请检查 bundle install 输出和站点配置。"
     }
 
     if ($NoServe) {