jiantw83
89463cd263
README 的工具用法、技能行為清單、連結規則與 wiki 技能本文，全部改寫成 目錄頁的區塊格式：參數名從整列改成整個區塊、key-col 的用途縮回只給轉檔 用、補上取標題與換引言的判準，並登錄新增的驗證腳本。 文件與工具講的不是同一件事，呼叫端就會照舊敘述傳整列的表格文字進去，寫出 半表格半條列的頁面。key-col 的語意變動最容易誤解——它從「要換掉哪一欄」 變成「轉檔時哪一欄持有身分」，敘述不改就會被填成別的欄位。 目錄頁條列、內容頁維持圖表優先，這個區分在每一份文件裡都寫明，避免把改版 範圍誤讀成整個 wiki。結束碼說明一併對回工具現況。 功能範圍：目錄頁版面改版的文件同步。
63 lines
3.6 KiB
Markdown
63 lines
3.6 KiB
Markdown
# 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`。不要自己組路徑：頁名有大小寫與編碼規則，手組的路徑看起來像對的，點下去是死的。
|
||
|
||
## 為什麼取消 `[[...]]`
|
||
|
||
三個理由，每一個都足以單獨取消它。
|
||
|
||
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 對私有存取庫的回應與「頁不存在」難以分辨。兩者混用，一次金鑰過期就把整批還在的頁判成死連結，接著這些頁會被當成壞連結刪掉或改寫。
|