feat(link): 連結一律寫成 [文字](絕對網址)，寫入前先驗證連得到
取消 [[頁名]] 與 [[顯示文字|頁名]] 兩種同 wiki 寫法，不再分「同存取庫」與 「跨存取庫」兩條規則。那種寫法只在自己那個 wiki 內解析，寫錯不報錯，畫面上 看起來像普通文字或死連結，巡不到也修不了。 連結寫進頁面前先過 jsc-gitea 的 link-check.sh，結束碼 0 才寫。驗證一律走 API， 不看網頁狀態碼：私有存取庫的網頁網址對未登入請求一律回 404，拿狀態碼判會把 好連結判成壞的。認證失敗回 7，與死連結的 1 分開，免得金鑰一過期就把還在的頁 整批判死。
This commit is contained in:
+50
-15
@@ -1,27 +1,62 @@
|
||||
# Wiki 頁之間的連結
|
||||
# Wiki 頁與文件的連結
|
||||
|
||||
寫 wiki 頁才需要這份規則。兩條規則任一條寫錯，連結會指向一個不存在的頁，畫面上看不出異常。
|
||||
寫 wiki 頁、議題或存放庫文件都適用這兩條規則。連結寫錯時畫面上看不出異常，所以規則寫在這裡，不靠當下判斷。
|
||||
|
||||
## 方向：顯示文字在左，頁名在右
|
||||
## 規則 A：文字加連結一律寫成 `[文字](絕對網址)`
|
||||
|
||||
Gitea 採 GitHub／Gollum 慣例：`[[顯示文字|頁名]]`。方向與 MediaWiki 相反。Gitea 原始碼（`modules/markup/html_link.go`）寫得很清楚：
|
||||
只有這一種寫法。`[[頁名]]` 與 `[[顯示文字|頁名]]` 全面取消，不再分「同存取庫」與「跨存取庫」兩種寫法。
|
||||
|
||||
> MediaWiki uses [[link|text]], while GitHub uses [[text|link]] … we prefer GitHub syntax
|
||||
| 情境 | 寫法 |
|
||||
| --- | --- |
|
||||
| 目錄頁指向內容頁（例：`PLAN_CONTENTS` → `PLAN_{HASH}`） | `[PLAN_{HASH}](https://…/wiki/PLAN_…)` |
|
||||
| 內容頁指向目錄頁，或指向別的型別 | `[顯示文字](絕對網址)` |
|
||||
| 目錄頁之間、同型別的內容頁之間 | `[顯示文字](絕對網址)` |
|
||||
| 議題、PR、存放庫檔案 | `[顯示文字](絕對網址)` |
|
||||
|
||||
所以 `[[PLAN_CONTENTS|我的計畫]]` 會顯示成文字 `PLAN_CONTENTS`，連到一個叫「我的計畫」的頁——這是壞連結。要寫 `[[我的計畫|PLAN_CONTENTS]]`。
|
||||
網址一律取自 `tools/gitea.sh wiki-url {owner}/{repo} {page}`，它讀 API 回應的 `html_url`。不要自己組路徑：頁名有大小寫與編碼規則，手組的路徑看起來像對的，點下去是死的。
|
||||
|
||||
顯示文字與頁名相同時，用不帶豎線的 `[[PLAN_CONTENTS]]`，這種寫法不會寫錯。
|
||||
## 為什麼取消 `[[...]]`
|
||||
|
||||
## 範圍：`[[...]]` 只在同一個 wiki 內解析
|
||||
三個理由，每一個都足以單獨取消它。
|
||||
|
||||
`[[...]]` 與 markdown 相對連結都只在目前這個 wiki 內解析。跨存取庫沒有 wiki 連結語法。
|
||||
1. `[[...]]` 只在目前這個 wiki 內解析。跨存取庫沒有這種語法，連結會落在自己這個 wiki 的同名頁上。
|
||||
2. 寫錯不會報錯。畫面上是一段普通文字或一條死連結，巡不到也修不了。
|
||||
3. 目錄頁住在 CONTENTS 專用存取庫，內容頁住在自己型別的存取庫。兩種寫法並存，就得逐處判斷兩端各自解到哪一個存取庫。統一成一種，這個判斷整個消失。
|
||||
|
||||
目錄頁全部住在 CONTENTS 專用存取庫，內容頁住在自己型別的存取庫。所以「同型別」不再等於「同存取庫」，判斷要看兩端各自解析到哪一個存取庫。
|
||||
另外還有一項成本：Gitea 的 markdown 渲染端點不吃 wiki 情境，`[[...]]` 會原樣輸出成字面括號。匯出成 HTML 或轉成議題時，每一條都得先換成絕對網址。一律寫絕對網址就沒有這道轉換。
|
||||
|
||||
| 連結 | 同一個 wiki？ | 寫法 |
|
||||
搬移舊頁時 `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，不帶金鑰 |
|
||||
|
||||
結束碼：
|
||||
|
||||
| 碼 | 意義 | 呼叫端該做的事 |
|
||||
| --- | --- | --- |
|
||||
| 目錄頁之間（例：`PLAN_CONTENTS` → `LOG_CONTENTS`） | 一定同一個：目錄頁都在 CONTENTS 存取庫 | `[[顯示文字\|頁名]]` 或 `[[頁名]]` |
|
||||
| 同型別的內容頁之間（例：`PLAN_{HASH}` → 另一頁 `PLAN_{HASH}`） | 一定同一個：一個型別一個存取庫 | `[[顯示文字\|頁名]]` 或 `[[頁名]]` |
|
||||
| 目錄頁與內容頁之間，以及跨型別（例：`PLAN_CONTENTS` → `PLAN_{HASH}`、`LOG_{HASH}` → `PLAN_{HASH}`） | **不保證**：兩端各自解析，可能不同 | `wiki-url` 給的絕對網址：`[顯示文字](https://…/wiki/PLAN_…)` |
|
||||
| 0 | 全部連得到 | 才可以寫入 |
|
||||
| 1 | 至少一筆連不到 | 不得寫入，回報 DEAD 那幾筆 |
|
||||
| 2 | 用法錯誤：一個網址都沒給 | 補上參數再呼叫 |
|
||||
| 3 | 清單裡有 Gitea 網址，但 `GITEA_HOST` 未設定 | 先設定再呼叫，不得跳過驗證 |
|
||||
| 7 | Gitea 認證失敗（401、403） | 停下來回報金鑰問題 |
|
||||
|
||||
目錄頁解 `JSC_WIKI_REPO_CONTENTS`，內容頁解自己的 `JSC_WIKI_REPO_{TYPE}`，兩端各解各的。只設 `JSC_WIKI_REPO` 時兩端會落在同一個存取庫，多設一個型別變數就分開了。所以這兩種連結**一律**用絕對網址：兩邊剛好同存取庫也照樣正確，不必分兩種寫法，也不必跟著環境變數改寫法。網址一律取自 `tools/gitea.sh wiki-url`，不要自己組路徑。
|
||||
Gitea 連結一律走 API，不看網頁狀態碼。私有存取庫的網頁網址對未登入請求一律回 404，用網頁狀態碼判斷會把好連結判成壞連結，接著整批砍掉還在的頁。
|
||||
|
||||
第 7 碼與第 1 碼分開的理由一樣：金鑰失效時，Gitea 對私有存取庫的回應與「頁不存在」難以分辨。兩者混用，一次金鑰過期就把整批還在的頁判成死連結，接著這些頁會被當成壞連結刪掉或改寫。
|
||||
|
||||
Reference in New Issue
Block a user