Starsoup Docs

Appearance

Starsoup Docs — 後續操作說明 ​

本文檔列出所有需要你手動完成的配置步驟。
VitePress 代碼、GitHub Actions workflow 已全部就緒，完成以下步驟即可實現全自動部署。

✅ 已完成（無需操作） ​

  • [x] VitePress 項目初始化（package.json, .vitepress/config.ts）
  • [x] Obsidian 語法兼容插件（.vitepress/plugins/obsidian.ts）
    • Wiki 連結 [Page](page), [Alias](page)
    • 圖片嵌入 ![](image.png)
    • Callout > [!NOTE] → VitePress container
    • 行內標籤 #tag → styled span
  • [x] 自定義主題（.vitepress/theme/）
  • [x] GitHub Actions deploy workflow（.github/workflows/deploy.yml）
  • [x] .gitignore 配置
  • [x] 首頁 docs/index.md 與歡迎頁 docs/guide.md
  • [x] 本地構建驗證通過（npm run docs:build）

📋 待你完成的步驟 ​

Step 1：生成 GitHub Personal Access Token (PAT) ​

  1. 前往 GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
  2. 點擊 Generate new token
  3. 設置：
    • Token name：DOCS_DEPLOY_TOKEN
    • Expiration：建議 90 天或更長
    • Repository access：選擇 Only select repositories，選中：
      • herointene/my-obsidian-vault
      • herointene/starsoup-docs
    • Permissions：
      • Repository permissions → Contents：Read and write（需要 checkout private repo）
      • Repository permissions → Metadata：Read-only（自動勾選）
  4. 複製生成的 Token（之後無法再查看）

⚠️ 如果使用 Classic token，則需要勾選 repo scope。

Step 2：在 my-obsidian-vault 倉庫設置 Secret ​

  1. 前往 https://github.com/herointene/my-obsidian-vault/settings/secrets/actions
  2. 點擊 New repository secret
  3. 設置：
    • Name：DOCS_DEPLOY_TOKEN
    • Secret：貼上 Step 1 生成的 PAT
  4. 點擊 Add secret

Step 3：在 starsoup-docs 倉庫設置 Secret ​

  1. 前往 https://github.com/herointene/starsoup-docs/settings/secrets/actions
  2. 點擊 New repository secret
  3. 添加以下兩個 Secret：
NameValue
DOCS_DEPLOY_TOKENStep 1 生成的 GitHub PAT
CF_API_TOKENCloudflare API Token（見 Step 5）
CF_ACCOUNT_IDCloudflare Account ID（見 Step 5）

Step 4：在 my-obsidian-vault 新增 trigger workflow ​

在 my-obsidian-vault 倉庫中創建以下文件：

文件路徑：.github/workflows/trigger-docs.yml

yaml
name: Trigger Docs Deploy

on:
  push:
    branches: [main]
    paths:
      - 'project/starsoup/**'

jobs:
  trigger:
    runs-on: ubuntu-latest
    steps:
      - name: Dispatch to starsoup-docs
        uses: peter-evans/repository-dispatch@v3
        with:
          token: ${{ secrets.DOCS_DEPLOY_TOKEN }}
          repository: herointene/starsoup-docs
          event-type: obsidian-updated

這是 my-obsidian-vault 倉庫中唯一需要新增的文件。

Step 5：配置 Cloudflare Pages ​

5a. 創建 Cloudflare Pages 項目 ​

  1. 登入 Cloudflare Dashboard
  2. 左側選單選擇 Workers & Pages
  3. 點擊 Create → Pages → Direct Upload (因為我們用 GitHub Actions 部署，不用連接 Git)
  4. Project name：starsoup-docs
  5. 上傳一個空資料夾或任意文件完成初始建立（之後 GitHub Actions 會覆蓋）

現在 workflow 已支援自動建立 starsoup-docs Pages 項目。
如果你不想手動建立，也可以直接略過這一步，首次部署時會自動建立。
但前提是 CF_ACCOUNT_ID 必須指向正確的 Cloudflare 帳號，且 CF_API_TOKEN 有足夠權限。

5b. 生成 Cloudflare API Token ​

  1. 前往 Cloudflare API Tokens
  2. 點擊 Create Token
  3. 選擇 Custom token (Edit template)
  4. 設置：
  • Token name：starsoup-docs-deploy
  • Account Resources：選擇你的 Cloudflare 帳號
  • Permissions：
ScopePermission
AccountCloudflare Pages: Edit
UserMemberships: Read
UserUser Details: Read
  1. 複製生成的 Token
  2. 將此 Token 作為 CF_API_TOKEN 添加到 starsoup-docs 的 GitHub Secrets（見 Step 3）

5c. 取得 Cloudflare Account ID ​

  1. 前往 Cloudflare Dashboard
  2. 進入你要部署 starsoup-docs 的帳號
  3. 在右側側欄或帳號總覽頁找到 Account ID
  4. 複製該值
  5. 在 starsoup-docs GitHub Secrets 中新增 CF_ACCOUNT_ID
  6. Secret 值填入剛才複製的 Account ID

5d.（可選）綁定自定義域名 ​

  1. 在 Cloudflare Pages 項目設置 → Custom domains
  2. 添加 docs.starsoup.com（需要域名在 Cloudflare DNS 中）

Step 6：推送 starsoup-docs 到 GitHub ​

bash
cd /home/ted/project/starsoup-docs
git add -A
git commit -m "feat: initialize VitePress with Obsidian plugin and CI/CD"
git push origin main

推送後，GitHub Actions 會自動觸發 deploy workflow。
如果出現 /memberships 認證錯誤，通常是 CF_API_TOKEN 缺少 User: Memberships Read 或 User: User Details Read，或者沒有設置 CF_ACCOUNT_ID。

更新：workflow 現在會在首次部署時自動建立 starsoup-docs Pages 項目。
如果仍然出現 Project not found，通常表示 CF_ACCOUNT_ID 指向了錯誤帳號，或 CF_API_TOKEN 無法在該帳號下建立 Pages 項目。

Step 7：驗證全鏈路 ​

  1. push starsoup-docs → 自動部署

  2. 修改 Obsidian → 觸發鏈路

    • 在 Obsidian 中修改 project/starsoup/ 下任意文件並保存
    • Obsidian Git 自動 push 後，查看 my-obsidian-vault Actions
    • 確認 Trigger Docs Deploy 成功
    • 確認 starsoup-docs 的 Deploy workflow 被觸發並成功

  3. 訪問網站

    • 打開 https://starsoup-docs.pages.dev（或你設置的自定義域名）
    • 確認內容已更新

🔧 故障排除 ​

問題排查方向
my-obsidian-vault trigger 無反應確認修改的文件在 project/starsoup/** 路徑下
repository_dispatch 失敗檢查 DOCS_DEPLOY_TOKEN 是否有 starsoup-docs 的 Contents 寫入權限
sparse checkout 失敗確認 DOCS_DEPLOY_TOKEN 是否有 my-obsidian-vault 的 Contents 讀取權限
Cloudflare 部署失敗確認 CF_API_TOKEN 有 Cloudflare Pages: Edit、User: Memberships Read、User: User Details Read；確認已設置 CF_ACCOUNT_ID 且指向正確帳號；若提示 Project not found，讓 workflow 自動建立或先手動建立 starsoup-docs
圖片無法顯示確保圖片在 project/starsoup/ 目錄下，並使用相對路徑引用
Wiki 連結 404確認目標頁面存在且文件名與連結一致（大小寫敏感）

📁 最終目錄結構 ​

starsoup-docs/
├── .github/
│   └── workflows/
│       └── deploy.yml              ← 部署流程
├── .vitepress/
│   ├── config.ts                   ← VitePress 配置
│   ├── plugins/
│   │   └── obsidian.ts             ← Obsidian 語法兼容
│   └── theme/
│       ├── index.ts                ← 主題入口
│       └── obsidian.css            ← 標籤樣式
├── docs/
│   ├── index.md                    ← 首頁
│   └── guide.md                    ← 歡迎頁
├── .gitignore
├── package.json
└── README.md
my-obsidian-vault/（僅新增一個文件）
└── .github/
    └── workflows/
        └── trigger-docs.yml        ← dispatch 觸發器