fix(wiki 連結): 方向修正與跨存取庫改用絕對網址（升版 0.0.6） #9

2026-08-24T10:54:54Z

jiantw83 commented

2026-08-24 10:54:54 +00:00

問題

wiki 頁之間的連結有兩個獨立的錯誤，兩個都會產生「看起來正常、點下去是空頁」的連結。

一、方向寫反（10 處）

Gitea 用 GitHub／Gollum 慣例 [[顯示文字|頁名]]——顯示文字在左、頁名在右，與 MediaWiki 相反。原始碼 modules/markup/html_link.go 的註解直說了：

// MediaWiki uses [[link|text]], while GitHub uses [[text|link]]
// It makes page handling terrible, but we prefer GitHub syntax

樣板寫的是 [[PLAN_{HASH}|{計畫名稱}]]，實際渲染成「顯示 PLAN_H…、連到一個叫做『計畫名稱』的頁」。

二、跨存取庫連結不可能用 [[...]]（8 處）

wiki/SKILL.md 明訂「不同頁型可以落在不同 {owner}/{repo}」，每個頁型各自解析 JSC_WIKI_REPO_{TYPE}。而 [[頁名]] 與 markdown 相對連結都只在當前 wiki 內解析，Gitea 沒有跨存取庫的 wiki 連結語法。所以 LOG_{HASH} 連到 PLAN_{HASH} 這種跨頁型連結，一旦兩個頁型設在不同存取庫就斷掉。

修法

分三類處理：

類別	處理	處數
同頁型（目錄頁 → 自己的內容頁，必定同庫）	交換管線兩邊	6
跨頁型（可能跨庫）	改用絕對網址，網址由新的 `wiki-url` 子指令取得	6
工作證	`TICKET_…` 不是 wiki 頁型（是 session 名稱），改成行內程式碼，不再假裝是連結	2

新增 gitea.sh wiki-url <owner>/<repo> <page>：從 API 回應的 html_url 取絕對網址，不自行組路徑。modules/structs/repo_wiki.go 的 WikiPageMetaData 確認有這個欄位：

Title      string `json:"title"`
HTMLURL    string `json:"html_url"`
SubURL     string `json:"sub_url"`

wiki/SKILL.md 新增「Linking between wiki pages」一節，把方向與作用範圍兩條規則寫死，附上判斷表（同頁型可用 [[...]]，跨頁型一律絕對網址，不要依「這次剛好同庫」來分支）。

注意事項

跨頁型連結即使兩個頁型目前設在同一個存取庫也用絕對網址——這樣設定改變時不會突然斷掉。
顯示文字與頁名相同時，用無管線的 [[PLAN_H…]]，方向不可能寫錯。
樣板的 {PLAN 頁絕對網址} 這類佔位符由 skill 在寫頁時以 wiki-url 的輸出填入。
未端到端實測：這台 Gitea 的 /markup 與 /markdown 渲染 API 都回空回應，plugins/* 也還沒建 wiki，所以上述結論是原始碼與 schema 級證據，不是實際渲染驗證。第一次真的寫 wiki 頁時值得順手確認一次。

## 問題 wiki 頁之間的連結有兩個獨立的錯誤，兩個都會產生「看起來正常、點下去是空頁」的連結。 **一、方向寫反（10 處）** Gitea 用 GitHub／Gollum 慣例 `[[顯示文字|頁名]]`——顯示文字在左、頁名在右，與 MediaWiki 相反。原始碼 `modules/markup/html_link.go` 的註解直說了： ```go // MediaWiki uses [[link|text]], while GitHub uses [[text|link]] // It makes page handling terrible, but we prefer GitHub syntax ``` 樣板寫的是 `[[PLAN_{HASH}|{計畫名稱}]]`，實際渲染成「顯示 `PLAN_H…`、連到一個叫做『計畫名稱』的頁」。 **二、跨存取庫連結不可能用 `[[...]]`（8 處）** `wiki/SKILL.md` 明訂「不同頁型可以落在不同 `{owner}/{repo}`」，每個頁型各自解析 `JSC_WIKI_REPO_{TYPE}`。而 `[[頁名]]` 與 markdown 相對連結**都只在當前 wiki 內解析**，Gitea 沒有跨存取庫的 wiki 連結語法。所以 `LOG_{HASH}` 連到 `PLAN_{HASH}` 這種跨頁型連結，一旦兩個頁型設在不同存取庫就斷掉。 ## 修法分三類處理： | 類別 | 處理 | 處數 | | --- | --- | --- | | 同頁型（目錄頁 → 自己的內容頁，必定同庫） | 交換管線兩邊 | 6 | | 跨頁型（可能跨庫） | 改用絕對網址，網址由新的 `wiki-url` 子指令取得 | 6 | | 工作證 | `TICKET_…` 不是 wiki 頁型（是 session 名稱），改成行內程式碼，不再假裝是連結 | 2 | 新增 `gitea.sh wiki-url <owner>/<repo> <page>`：從 API 回應的 `html_url` 取絕對網址，**不自行組路徑**。`modules/structs/repo_wiki.go` 的 `WikiPageMetaData` 確認有這個欄位： ```go Title string `json:"title"` HTMLURL string `json:"html_url"` SubURL string `json:"sub_url"` ``` `wiki/SKILL.md` 新增「Linking between wiki pages」一節，把方向與作用範圍兩條規則寫死，附上判斷表（同頁型可用 `[[...]]`，跨頁型一律絕對網址，不要依「這次剛好同庫」來分支）。 ## 注意事項 - 跨頁型連結**即使兩個頁型目前設在同一個存取庫也用絕對網址**——這樣設定改變時不會突然斷掉。 - 顯示文字與頁名相同時，用無管線的 `[[PLAN_H…]]`，方向不可能寫錯。 - 樣板的 `{PLAN 頁絕對網址}` 這類佔位符由 skill 在寫頁時以 `wiki-url` 的輸出填入。 - **未端到端實測**：這台 Gitea 的 `/markup` 與 `/markdown` 渲染 API 都回空回應，`plugins/*` 也還沒建 wiki，所以上述結論是原始碼與 schema 級證據，不是實際渲染驗證。第一次真的寫 wiki 頁時值得順手確認一次。

jiantw83 added 2 commits 2026-08-24 10:54:55 +00:00

fix(wiki 連結): 跨頁型連結改用絕對網址 fdf6b2b771

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

chore(plugin 版本): 三份 manifest 升版至 0.0.6 5d12ad6f43

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

jiantw83 added a new dependency 2026-08-24 10:55:05 +00:00

plugins/gitea#13 - fix(wiki 連結): 方向修正與跨存取庫改用絕對網址（升版 0.0.8）

admin merged commit 6f28e1ae84 into develop

2026-08-24 11:00:30 +00:00

admin deleted branch fix/wiki-link-direction-and-scope

2026-08-24 11:00:30 +00:00

jiantw83 referenced this pull request

2026-08-24 11:01:19 +00:00

發佈 jsc-log 0.0.6：跨頁型連結改用絕對網址 #10

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Depends on

#13 fix(wiki 連結): 方向修正與跨存取庫改用絕對網址（升版 0.0.8）

plugins/gitea

Reference: plugins/log#9