# Wiki 頁與文件的連結

寫 wiki 頁、議題或存放庫文件都適用這兩條規則。連結寫錯時畫面上看不出異常，所以規則寫在這裡，不靠當下判斷。

## 規則 A：文字加連結一律寫成 `[文字](絕對網址)`

只有這一種寫法。`[[頁名]]` 與 `[[顯示文字|頁名]]` 全面取消，不再分「同存取庫」與「跨存取庫」兩種寫法。

| 情境 | 寫法 |
| --- | --- |
| 目錄頁指向內容頁（例：`PLAN_CONTENTS` → `PLAN_{HASH}`） | `[PLAN_{HASH}](https://…/wiki/PLAN_…)` |
| 內容頁指向目錄頁，或指向別的型別 | `[顯示文字](絕對網址)` |
| 目錄頁之間、同型別的內容頁之間 | `[顯示文字](絕對網址)` |
| 議題、PR、存放庫檔案 | `[顯示文字](絕對網址)` |

網址一律取自 `tools/gitea.sh wiki-url {owner}/{repo} {page}`，它讀 API 回應的 `html_url`。不要自己組路徑：頁名有大小寫與編碼規則，手組的路徑看起來像對的，點下去是死的。

## 為什麼取消 `[[...]]`

三個理由，每一個都足以單獨取消它。

1. `[[...]]` 只在目前這個 wiki 內解析。跨存取庫沒有這種語法，連結會落在自己這個 wiki 的同名頁上。
2. 寫錯不會報錯。畫面上是一段普通文字或一條死連結，巡不到也修不了。
3. 目錄頁住在 CONTENTS 專用存取庫，內容頁住在自己型別的存取庫。兩種寫法並存，就得逐處判斷兩端各自解到哪一個存取庫。統一成一種，這個判斷整個消失。

另外還有一項成本：Gitea 的 markdown 渲染端點不吃 wiki 情境，`[[...]]` 會原樣輸出成字面括號。匯出成 HTML 或轉成議題時，每一條都得先換成絕對網址。一律寫絕對網址就沒有這道轉換。

搬移舊頁時 `tools/migrate-wiki.sh` 仍會改寫舊頁裡殘留的 `[[...]]`，那是清理既有內容，不是允許新寫。

## 規則 B：連結先驗證連得到，才寫進文件

寫入前，把每一個要放進頁面的連結交給 `tools/link-check.sh`。結束碼 0 才 `wiki-put`。

```
link-check.sh {網址}...
printf '%s\n' {網址}... | link-check.sh
```

每個網址印一行，三欄以 TAB 分隔：`{OK|DEAD|SKIP}<TAB>{網址}<TAB>{說明}`。

驗證方式依網址種類分流：

| 網址種類 | 驗證方式 |
| --- | --- |
| Gitea wiki 頁（`{GITEA_HOST}/{owner}/{repo}/wiki/{頁名}`） | 轉成 API `/repos/{owner}/{repo}/wiki/page/{頁名}` |
| Gitea 議題（`…/issues/{編號}`） | API `/repos/{owner}/{repo}/issues/{編號}` |
| 其他 Gitea 網址 | HTTP HEAD，帶金鑰 |
| 非 Gitea 的外部網址 | HTTP HEAD，不帶金鑰 |

結束碼：

| 碼 | 意義 | 呼叫端該做的事 |
| --- | --- | --- |
| 0 | 全部連得到 | 才可以寫入 |
| 1 | 至少一筆連不到 | 不得寫入，回報 DEAD 那幾筆 |
| 2 | 用法錯誤：一個網址都沒給 | 補上參數再呼叫 |
| 3 | 清單裡有 Gitea 網址，但 `GITEA_HOST` 未設定 | 先設定再呼叫，不得跳過驗證 |
| 7 | Gitea 認證失敗（401、403） | 停下來回報金鑰問題 |

Gitea 連結一律走 API，不看網頁狀態碼。私有存取庫的網頁網址對未登入請求一律回 404，用網頁狀態碼判斷會把好連結判成壞連結，接著整批砍掉還在的頁。

第 7 碼與第 1 碼分開的理由一樣：金鑰失效時，Gitea 對私有存取庫的回應與「頁不存在」難以分辨。兩者混用，一次金鑰過期就把整批還在的頁判成死連結，接著這些頁會被當成壞連結刪掉或改寫。