jiantw83
89463cd263
README 的工具用法、技能行為清單、連結規則與 wiki 技能本文，全部改寫成 目錄頁的區塊格式：參數名從整列改成整個區塊、key-col 的用途縮回只給轉檔 用、補上取標題與換引言的判準，並登錄新增的驗證腳本。 文件與工具講的不是同一件事，呼叫端就會照舊敘述傳整列的表格文字進去，寫出 半表格半條列的頁面。key-col 的語意變動最容易誤解——它從「要換掉哪一欄」 變成「轉檔時哪一欄持有身分」，敘述不改就會被填成別的欄位。 目錄頁條列、內容頁維持圖表優先，這個區分在每一份文件裡都寫明，避免把改版 範圍誤讀成整個 wiki。結束碼說明一併對回工具現況。 功能範圍：目錄頁版面改版的文件同步。
3.6 KiB
3.6 KiB
Wiki 頁與文件的連結
寫 wiki 頁、議題或存放庫文件都適用這兩條規則。連結寫錯時畫面上看不出異常，所以規則寫在這裡，不靠當下判斷。
規則 A：文字加連結一律寫成 [文字](絕對網址)
只有這一種寫法。[[頁名]] 與 [[顯示文字|頁名]] 全面取消，不再分「同存取庫」與「跨存取庫」兩種寫法。
| 情境 | 寫法 |
|---|---|
目錄頁指向內容頁（例：PLAN_CONTENTS → PLAN_{HASH}）：連結寫在該筆 H2 區塊的條列裡，H2 標題本身只放頁名，不放連結 |
- 計畫頁：[PLAN_{HASH}](https://…/wiki/PLAN_…) |
| 內容頁指向目錄頁，或指向別的型別 | [顯示文字](絕對網址) |
| 目錄頁之間、同型別的內容頁之間 | [顯示文字](絕對網址) |
| 議題、PR、存放庫檔案 | [顯示文字](絕對網址) |
網址一律取自 tools/gitea.sh wiki-url {owner}/{repo} {page}，它讀 API 回應的 html_url。不要自己組路徑：頁名有大小寫與編碼規則，手組的路徑看起來像對的，點下去是死的。
為什麼取消 [[...]]
三個理由，每一個都足以單獨取消它。
[[...]]只在目前這個 wiki 內解析。跨存取庫沒有這種語法，連結會落在自己這個 wiki 的同名頁上。- 寫錯不會報錯。畫面上是一段普通文字或一條死連結，巡不到也修不了。
- 目錄頁住在 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 對私有存取庫的回應與「頁不存在」難以分辨。兩者混用，一次金鑰過期就把整批還在的頁判成死連結，接著這些頁會被當成壞連結刪掉或改寫。