abertanha/md-to-wiki-docs-skills

md-to-wiki — 輕量路由器 (第二階段)

將 Markdown 規格文件轉換為文件網站。

觸發關鍵字： "建立 wiki", "生成文件", "發布規格", "製作網站", "從 markdown 建立 wiki", "繪製圖表", "流程圖", "架構圖", "狀態圖", "序列圖"

階段路由器

分析用戶請求以決定採用哪條路徑：

lower=$(echo "$1" | tr '[:upper:]' '[:lower:]')
case "$lower" in
  *"not sure"*|*"help"*|*"recommend"*)     ROUTE="onboarding" ;;
  *"html"*|*"site"*|*"mkdocs"*|*"material"*)  ROUTE="mkdocs" ;;
  *"swagger"*|*"openapi"*|*"api"*)          ROUTE="swagger" ;;
  *"github wiki"*|*"wiki tab"*)             ROUTE="github-wiki" ;;
  *"dokuwiki"*|*"doku"*)                    ROUTE="dokuwiki" ;;
  *"pdf"*|*"print"*|*"book"*)               ROUTE="pdf" ;;
  *"reference"*|*"issue"*|*"pr"*|*"pull"*)  ROUTE="references" ;;
  *"deploy"*|*"publish"*|*"go live"*)       ROUTE="deploy" ;;
  *)                                          ROUTE="onboarding" ;;
esac

然後啟動相應的代理程式：

路徑	代理程式	說明
onboarding	agents/onboarding.md	訪談使用者，偵測作業系統，設定 SKILL_DIR
mkdocs	agents/format-mkdocs.md	產生 MkDocs Material 網站
swagger	agents/format-swagger.md	產生 OpenAPI 3.0 + Swagger UI
github-wiki	agents/format-github-wiki.md	發布至 GitHub Wiki
dokuwiki	agents/format-dokuwiki.md	轉換為 DokuWiki 格式
pdf	agents/format-pdf.md	透過 Pandoc 產生 PDF
references	agents/references.md	使用 GitHub issue/PR 參考資訊豐富文件
deploy	agents/deploy.md	將生成的文件部署至主機服務

執行流程

1. 上路 → 詢問問題：專案名稱、來源目錄、目標讀者（開發者/利害關係人/一般大眾）、期望格式。偵測作業系統一次，儲存 SKILL_DIR、SCRIPT_EXT、SCRIPT_RUNNER。
2. 格式生成 → 載入對應的格式代理程式。使用 scripts/ 中的配套腳本，搭配 $SCRIPT_RUNNER 執行。
3. 參考資訊 → 若使用者需要 issue/PR 參考，載入 references.md。
4. 部署 → 生成完成後，載入 deploy.md 以提供主機服務選項。

全域變數（上路階段設定一次）

• SKILL_DIR — 此技能資料夾的解析路徑
• SCRIPT_EXT — .sh 或 .ps1
• SCRIPT_RUNNER — "" 或 "powershell -File"
• OS_TYPE — unix 或 windows
• PROJECT_NAME — 來自使用者
• SOURCES — 規格檔案的路徑
• AUDIENCE — developer、stakeholder 或 general

配套腳本

所有腳本在 .sh 與 .ps1 中接受相同的位置參數：

腳本	用途
discover-sources	掃描目錄以尋找規格/專案/程式碼庫/快速檔案
generate-mkdocs	建立完整的 mkdocs.yml 與頁面結構
generate-index	根據目標讀者建立合適的登陸頁面
to-dokuwiki	將 Markdown 轉換為 DokuWiki 語法
to-pdf	合併並透過 pandoc 轉換為 PDF
fetch-issues	快取 GitHub issue/PR 元資料

多目錄輸入

將多個來源目錄合併至 merged-specs/ 後再執行：

mkdir -p merged-specs && cp -r .specs/* docs/* merged-specs/

分享

將 md-to-wiki/ 複製到同事的 .config/opencode/skills/ 或 .opencode/skills/ 中。依賴的套件依格式而異。