docs(templates): 五個目錄頁範本改成大標題加條列
What
- `templates/plan-contents.md`、`templates/analyze-contents.md`、`templates/repo-contents.md`、`templates/deliver-contents.md`、`templates/maintain-contents.md` 的版面從 markdown 表格改成一筆一個 H2 區塊,欄位改成標題底下的一層條列。
- 四個有內容頁的型別,H2 標題寫成該筆對應內容頁的實際頁名;`MAINTAIN` 沒有內容頁,標題改用該存取庫的 `{owner}/{repo}`。
- 各範本的引言補上版面段,並把寫入語意從「單列 upsert」改寫成單一區塊 upsert,末端的示範資料改成一個完整的 H2 區塊。
- 引言裡寫明鍵欄的語意與各頁的正確序號,並點出填錯的靜默後果。
Why
- 目錄頁是全部使用者共用的索引。表格一寬就得橫向捲、欄位一多就對不上表頭,而且併行寫入時只要有人少打一根豎線,整張表就散掉,別人那一筆跟著看不見。
- 條列式一筆一個區塊,寫入端只換自己那一塊,壞掉也只壞自己那一塊。
- `MAINTAIN` 整個型別只有目錄頁,硬套內容頁頁名當標題會指向一個不存在的頁;存取庫名不會漂移,當鍵一樣穩。
- 鍵欄填錯時工具不會報錯,既有那一筆會被當成新的附加到頁尾,同一筆變兩個區塊,舊區塊從此再也更新不到,所以範本要把序號寫死。
How
- 一頁固定三段:H1 頁名、`>` 引言、然後每一筆一個 H2 區塊;欄位格式 `- {欄位名}:{值}`,全形冒號,順序照原本的欄位從左到右,鍵那一欄照樣留一條。
- 寫入示例統一成 `wiki-contents.sh upsert {TYPE} {鍵欄} "{鍵}" {區塊檔} [{本範本}]`,並註明第四個引數是整個 H2 區塊的 markdown,不是列檔。
- 頁上不留任何 markdown 表格;內容頁範本不在本輪範圍,維持圖表優先。
Who
- 影響照這五個範本寫目錄頁的四支階段技能。
- 舊表格頁的自動轉檔與單一區塊 upsert 的實作不在本存取庫,本存取庫只提供範本與敘述。
This commit is contained in:
@@ -1,11 +1,17 @@
|
||||
# 分析目錄
|
||||
|
||||
> 存放位置:本頁是目錄頁,落在 `JSC_WIKI_REPO_CONTENTS` 解出的專用存取庫(沒設定就退回 `JSC_WIKI_REPO`,都沒設定就停)。分析頁 `ANALYZE_{HASH}` 住在 `JSC_WIKI_REPO_ANALYZE` 那一邊,兩者不同存取庫。
|
||||
> 寫入語意:一列代表一份分析頁。一律用 `jsc-gitea/tools/wiki-contents.sh upsert ANALYZE 3 {HASH} {列檔} {本範本}` 單列寫回:該分析頁已經有列就更新那一列,沒有才附加一列,整頁一起送出。禁止整頁覆蓋,也不得改動別人的列。
|
||||
> 版面:一個 H1 頁名、一段 `>` 引言,接著每一筆一個 H2 區塊。H2 標題就是該筆分析頁的實際頁名(示範區塊寫成 `ANALYZE_{HASH}` 只是佔位符,真正要填的是 `jsc-sdlc:analyze` 剛寫出去那一頁的頁名,線上實際長成 `ANALYZE_20260821_100552_104F0709` 這樣),標題不放連結、不加前後綴。欄位是標題底下的一層條列,一欄一條,格式 `- {欄位名}:{值}`。本頁不留 markdown 表格。
|
||||
> 寫入語意:一個區塊代表一份分析頁。一律用 `jsc-gitea/tools/wiki-contents.sh upsert ANALYZE 2 {分析頁頁名} {區塊檔} {本範本}` 單筆寫回:該分析頁已經有區塊就更新那個區塊,沒有才附加一個區塊,整頁一起送出。禁止整頁覆蓋,也不得改動別人的區塊。參數語意:`2` 是舊表格裡持有內容頁連結那一欄的序號,也就是「分析頁」欄,只供自動轉檔用——本頁還是舊表格時,腳本從那一欄的連結網址取最後一段路徑當 H2 標題;本頁已經是條列版面就完全忽略它。這個序號填錯,轉出來的標題就跟鍵對不上,既有那一筆會被當成新的附加上去,同一份分析變成兩個區塊,舊區塊從此再也更新不到,所以不是死參數、也不能隨便填。`{分析頁頁名}` 是 H2 標題,填這一筆對應內容頁的實際頁名,也就是技能自己剛寫的那一頁的頁名,不套 `ANALYZE_{HASH}` 的公式;`{區塊檔}` 是整個 H2 區塊的 markdown(`## {分析頁頁名}` 那一行加各條欄位),不是列檔。
|
||||
> 連結寫法:一律寫成 `[{文字}]({連結})`。分析頁欄位的連結放 `jsc-gitea/tools/gitea.sh wiki-url` 給的絕對網址,不自行組路徑,也不用 `[[頁名]]` 或 `[[顯示文字|頁名]]`:後者只在同一個 wiki 內解析,寫錯不會報錯,畫面上看起來像純文字或死連結,巡不到也修不了。
|
||||
> 寫入前驗證:要放進本頁的每一個連結先交給 `jsc-gitea/tools/link-check.sh`,結束碼 0 才寫入。有一筆 DEAD 就整列不寫,把連不到的清單回報給呼叫端。驗證走 API,不看網頁狀態碼:私有存取庫的網頁網址對沒帶金鑰的請求一律回 404,照狀態碼判會把還活著的頁判成死連結。結束碼 `1`=至少一筆連不到、`2`=一個網址都沒給、`3`=`GITEA_HOST` 未設定、`7`=金鑰失效,停下回報金鑰問題,不得當成連不到。
|
||||
> 寫入前驗證:要放進本頁的每一個連結先交給 `jsc-gitea/tools/link-check.sh`,結束碼 0 才寫入。有一筆 DEAD 就整個區塊不寫,把連不到的清單回報給呼叫端。驗證走 API,不看網頁狀態碼:私有存取庫的網頁網址對沒帶金鑰的請求一律回 404,照狀態碼判會把還活著的頁判成死連結。結束碼 `1`=至少一筆連不到、`2`=一個網址都沒給、`3`=`GITEA_HOST` 未設定、`7`=金鑰失效,停下回報金鑰問題,不得當成連不到。
|
||||
> HASH:由 `jsc-gitea/tools/hash-id` 對 `{owner}/{repo}` 算出的完整 40 碼大寫十六進位,不截短、不加前綴。
|
||||
|
||||
| 計畫名稱 | 分析頁 | HASH | 工作包 | 未完成項目 | 狀態 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| {計畫名稱} | [{計畫名稱}](https://{gitea 主機}/{owner}/{repo}/wiki/ANALYZE_{HASH}) | {HASH} | WP-01、WP-02 | {n} | 未完成 |
|
||||
## ANALYZE_{HASH}
|
||||
|
||||
- 計畫名稱:{計畫名稱}
|
||||
- 分析頁:[{計畫名稱}](https://{gitea 主機}/{owner}/{repo}/wiki/ANALYZE_{HASH})
|
||||
- HASH:{HASH}
|
||||
- 工作包:WP-01、WP-02
|
||||
- 未完成項目:{n}
|
||||
- 狀態:未完成
|
||||
|
||||
Reference in New Issue
Block a user