docs(gitea): 同步文件與參考資料

What：更新 README、AGENTS.md、templates 與 references，讓文件敘述與實際行為一致。 Why：稽核發現多處文件與程式行為分歧，違反「每個意義只有單一真實來源」。 How：以實際程式行為為準改寫敘述，重複的規則收成單一來源並以一行指引指過去。 Who：jsc-meta:skill-check 例行稽核（2026-08-25）。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-25 14:58:54 +08:00
parent 36fc4de73c
commit 3a2eb40bef
2 changed files with 36 additions and 3 deletions
@@ -0,0 +1,24 @@
+# Wiki 頁之間的連結
+
+寫 wiki 頁才需要這份規則。兩條規則任一條寫錯，連結會指向一個不存在的頁，畫面上看不出異常。
+
+## 方向：顯示文字在左，頁名在右
+
+Gitea 採 GitHub／Gollum 慣例：`[[顯示文字|頁名]]`。方向與 MediaWiki 相反。Gitea 原始碼（`modules/markup/html_link.go`）寫得很清楚：
+
+> MediaWiki uses [[link|text]], while GitHub uses [[text|link]] … we prefer GitHub syntax
+
+所以 `[[PLAN_H1234567|我的計畫]]` 會顯示成文字 `PLAN_H1234567`，連到一個叫「我的計畫」的頁——這是壞連結。要寫 `[[我的計畫|PLAN_H1234567]]`。
+
+顯示文字與頁名相同時，用不帶豎線的 `[[PLAN_H1234567]]`，這種寫法不會寫錯。
+
+## 範圍：`[[...]]` 只在同一個 wiki 內解析
+
+`[[...]]` 與 markdown 相對連結都只在目前這個 wiki 內解析。跨存取庫沒有 wiki 連結語法。
+
+| 連結 | 同一個 wiki？ | 寫法 |
+| --- | --- | --- |
+| 同頁面類型（例：`PLAN_CONTENTS` → `PLAN_{HASH}`） | 一定同一個：一個類型一個存取庫 | `[[顯示文字\|頁名]]` 或 `[[頁名]]` |
+| 不同頁面類型（例：`LOG_{HASH}` → `PLAN_{HASH}`） | **只有兩個類型解析到同一個存取庫時才同一個** | `wiki-url` 給的絕對網址：`[顯示文字](https://…/wiki/PLAN_…)` |
+
+每個類型各自解析自己的 `JSC_WIKI_REPO_{TYPE}`，所以跨類型連結**一律**用絕對網址：兩個類型剛好同存取庫也照樣正確，不必分兩種寫法。網址一律取自 `tools/gitea.sh wiki-url`，不要自己組路徑。