From 6719f33f97de4b5219614664aec9e7525f21c76e Mon Sep 17 00:00:00 2001
From: Nakano Kenji <Kuroinekorachi@gmail.com>
Date: Sun, 1 Feb 2026 22:55:06 +0800
Subject: [PATCH] docs: clarify wiki initialization for publish

- Document one-time wiki "Create the first page" requirement
- Improve Publish Wiki workflow error message
---
 .github/workflows/publish-wiki.yml |  2 +-
 docs/wiki/Wiki-Sync.md             | 13 ++++++++++++-
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/publish-wiki.yml b/.github/workflows/publish-wiki.yml
index b25c00c..8026b23 100644
--- a/.github/workflows/publish-wiki.yml
+++ b/.github/workflows/publish-wiki.yml
@@ -38,7 +38,7 @@ jobs:
 
           rm -rf wiki
           if ! git ls-remote "$wiki_repo" > /dev/null 2>&1; then
-            echo "::error::Unable to access wiki repo. Ensure Wiki is enabled in repository Settings -> Features -> Wiki."
+            echo "::error::Unable to access wiki repo. Ensure Wiki is enabled AND the first wiki page has been created (Wiki -> Create the first page)."
             exit 1
           fi
 
diff --git a/docs/wiki/Wiki-Sync.md b/docs/wiki/Wiki-Sync.md
index f8ed5ce..883e263 100644
--- a/docs/wiki/Wiki-Sync.md
+++ b/docs/wiki/Wiki-Sync.md
@@ -9,7 +9,18 @@
 进入 GitHub 仓库：
 - Settings -> Features -> 勾选 **Wiki**
 
-若未启用，Actions 会在克隆 `${repo}.wiki.git` 时失败。
+若未启用，Actions 会在访问 `${repo}.wiki.git` 时失败。
+
+### 1.1) 首次初始化（非常重要）
+
+GitHub 的 Wiki git 仓库（`${repo}.wiki.git`）通常需要**先创建第一篇 Wiki 页面**才会真正生成。
+
+做法：
+- 打开仓库的 Wiki：`https://github.com/<owner>/<repo>/wiki`
+- 点击 **Create the first page**
+- 保存（即使只写一行也可以）
+
+完成后，再触发一次同步（重新 push，或手动运行 `Publish Wiki` 工作流）即可。
 
 ---