diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 26b5be0..4a302c8 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-gitea", - "version": "0.0.7", + "version": "0.0.8", "description": "Gitea API 工具、Wiki 讀寫與存取庫批次同步", "skills": "./skills", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index e1a061d..e04331f 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-gitea", - "version": "0.0.7", + "version": "0.0.8", "description": "Gitea API 工具、Wiki 讀寫與存取庫批次同步", "skills": "./skills" } diff --git a/README.md b/README.md index d51c985..71029b3 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,7 @@ gitea.sh wiki-repo # 解析頁面類型的 wiki gitea.sh wiki-list / gitea.sh wiki-get / # 不存在 exit 4 gitea.sh wiki-put / # 自動判斷新建或更新 +gitea.sh wiki-url / # 印出 wiki 頁絕對網址(取自 API 的 html_url);跨存取庫連結用 gitea.sh pr-create / <body-file> gitea.sh api <METHOD> <path> [json-file] hash-id <text> # 與 gitea.sh hash-id 相同 diff --git a/plugin.json b/plugin.json index a033ff0..663cfe1 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-gitea", - "version": "0.0.7", + "version": "0.0.8", "description": "Gitea API 工具、Wiki 讀寫與存取庫批次同步", "skills": "./skills/" } diff --git a/skills/wiki/SKILL.md b/skills/wiki/SKILL.md index 8be55d4..5b8d7dd 100644 --- a/skills/wiki/SKILL.md +++ b/skills/wiki/SKILL.md @@ -22,6 +22,22 @@ Different page types can live in different `{owner}/{repo}` repos, classified by | list pages | `tools/gitea.sh wiki-list {owner}/{repo}` | | read page | `tools/gitea.sh wiki-get {owner}/{repo} {page}` (exit 4 when missing) | | write page | write the content to a temp file first, then `tools/gitea.sh wiki-put {owner}/{repo} {page} {file}` (creates or updates automatically) | +| page URL | `tools/gitea.sh wiki-url {owner}/{repo} {page}` — the page's absolute URL, taken from the API's `html_url` (exit 4 when the page is missing) | + +## Linking between wiki pages + +Two rules, and getting either wrong produces a link that silently points at a page that does not exist. + +**Direction**: Gitea uses the GitHub/Gollum convention — `[[display text|page name]]`, **display text on the LEFT, page name on the RIGHT**. This is the opposite of MediaWiki. Gitea's own source says so (`modules/markup/html_link.go`): *"MediaWiki uses [[link|text]], while GitHub uses [[text|link]] … we prefer GitHub syntax"*. So `[[PLAN_H1234567|我的計畫]]` renders as the text `PLAN_H1234567` linking to a page named 我的計畫 — broken. Write `[[我的計畫|PLAN_H1234567]]`. When display text and page name are the same, use the no-pipe form `[[PLAN_H1234567]]`, which cannot be got wrong. + +**Scope**: `[[...]]` and relative markdown links both resolve **only inside the current wiki**. There is no cross-repo wiki-link syntax. + +| Link | Same wiki? | Use | +| --- | --- | --- | +| Same page type (e.g. `PLAN_CONTENTS` → `PLAN_{HASH}`) | Always — one type, one repo | `[[display\|page]]` or `[[page]]` | +| Different page type (e.g. `LOG_{HASH}` → `PLAN_{HASH}`) | **Only when both types resolve to the same repo** | Absolute URL from `wiki-url`: `[display](https://…/wiki/PLAN_…)` | + +Because each type resolves its own `JSC_WIKI_REPO_{TYPE}`, a cross-type link **must** use the absolute URL — it stays correct whether or not the two types happen to share a repo, so never branch on that. Get the URL from `wiki-url`, never hand-assemble the path. ## Rules diff --git a/tools/gitea.sh b/tools/gitea.sh index 2f1363d..cb0e8eb 100755 --- a/tools/gitea.sh +++ b/tools/gitea.sh @@ -138,6 +138,22 @@ import json,sys,base64 d=json.load(sys.stdin) sys.stdout.write(base64.b64decode(d.get("content_base64","")).decode("utf-8")) ' ;; + wiki-url) + # 印出 wiki 頁的絕對網址,取自 API 回應的 html_url,不自行組路徑。 + # 跨存取庫連結(例如 LOG 頁連到 PLAN 頁,而兩者的 JSC_WIKI_REPO_{TYPE} 不同) + # 只有絕對網址會通:[[頁名]] 與 markdown 相對連結都只在同一個 wiki 內解析。 + or="${1:?owner/repo required}"; page="${2:?page required}" + if ! out=$(req GET "/repos/$or/wiki/page/$page" 2>/dev/null); then + echo "wiki page not found: $page" >&2; exit 4 + fi + url=$(printf '%s' "$out" | python3 -c ' +import json,sys +sys.stdout.write(json.load(sys.stdin).get("html_url") or "") +') + if [ -z "$url" ]; then + echo "wiki page has no html_url: $page" >&2; exit 5 + fi + printf '%s\n' "$url" ;; wiki-put) or="${1:?owner/repo required}"; page="${2:?page required}"; file="${3:?content file required}" tmp=$(mktemp)