Starsoup Docs — 設計文檔

項目名稱：starsoup-docs
版本：v1.0
狀態：設計階段
最後更新：2026-03-19

1. 背景與目標

1.1 背景

Starsoup 現有一個 Obsidian vault（my-obsidian-vault），由 Obsidian Git 插件自動同步至 GitHub。vault 內的 project/starsoup/ 子目錄存放 Starsoup 相關的項目文檔與筆記，需要以靜態網站形式對外或對內發布。

1.2 核心目標

將 my-obsidian-vault/project/starsoup/ 的 Markdown 內容發布為 VitePress 靜態網站
不修改現有 my-obsidian-vault 倉庫的任何目錄結構
實現「保存筆記 → 自動上線」的全自動部署鏈路
兼容 Obsidian 特有語法（Wiki 連結、Callout 等）

1.3 非目標

不合并兩個倉庫
不使用定時同步（避免延遲）
不需要手動觸發部署

2. 系統架構

2.1 總體架構

my-obsidian-vault (GitHub, 現有倉庫)
    └── project/starsoup/         ← 內容來源

starsoup-docs (GitHub, 新建倉庫)
    ├── .vitepress/               ← VitePress 配置
    └── docs/                     ← CI 環境臨時目錄（不 commit）

Cloudflare Pages                  ← 靜態托管

2.2 部署流程（Sequence）

你 (Obsidian)
    │ 保存筆記，Obsidian Git 自動 push
    ▼
my-obsidian-vault (GitHub)
    │ 觸發 trigger-docs.yml
    │ 偵測 project/starsoup/ 是否有改動
    │ 若有 → 發送 repository_dispatch 到 starsoup-docs
    ▼
starsoup-docs (GitHub Actions)
    │ sparse checkout my-obsidian-vault/project/starsoup/
    │ 複製內容到 docs/
    │ npm ci → vitepress build
    ▼
Cloudflare Pages
    │ 部署 .vitepress/dist/
    ▼
網站更新完成（約 2-3 分鐘）

2.3 觸發條件

事件	觸發結果
`my-obsidian-vault` push，且 `project/starsoup/**` 有改動	觸發完整部署
`my-obsidian-vault` push，但其他目錄改動	不觸發，跳過
`starsoup-docs` main branch push（修改 VitePress 配置）	觸發完整部署

3. 倉庫設計

3.1 my-obsidian-vault（現有倉庫，僅新增 workflow）

新增文件：

my-obsidian-vault/
└── .github/
    └── workflows/
        └── trigger-docs.yml      ← 唯一新增文件

不修改任何現有目錄結構。

3.2 starsoup-docs（新建倉庫）

完整目錄結構：

starsoup-docs/
├── .github/
│   └── workflows/
│       └── deploy.yml
├── .vitepress/
│   ├── config.ts
│   └── plugins/
│       └── obsidian.ts           ← Obsidian 語法兼容插件
├── docs/                         ← 加入 .gitignore，僅存在於 CI
├── .gitignore
└── package.json

4. CI/CD 配置

4.1 my-obsidian-vault — 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

4.2 starsoup-docs — deploy.yml

yaml

name: Deploy

on:
  repository_dispatch:
    types: [obsidian-updated]
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout VitePress repo
        uses: actions/checkout@v4

      - name: Sparse checkout Obsidian content
        uses: actions/checkout@v4
        with:
          repository: herointene/my-obsidian-vault
          token: ${{ secrets.DOCS_DEPLOY_TOKEN }}
          sparse-checkout: project/starsoup
          sparse-checkout-cone-mode: true
          path: obsidian-content

      - name: Copy content to docs/
        run: |
          rm -rf docs
          cp -r obsidian-content/project/starsoup docs

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - run: npm ci
      - run: npm run docs:build

      - name: Deploy to Cloudflare Pages
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CF_API_TOKEN }}
          command: pages deploy .vitepress/dist --project-name=starsoup-docs

5. VitePress 配置

5.1 .vitepress/config.ts

typescript

import { defineConfig } from 'vitepress'
import { obsidianPlugin } from './plugins/obsidian'

export default defineConfig({
  srcDir: './docs',
  title: 'Starsoup Docs',
  description: 'Starsoup 項目文檔',

  markdown: {
    config: (md) => {
      md.use(obsidianPlugin)
    }
  },

  srcExclude: [
    '**/templates/**',
    '**/.trash/**',
    '**/private/**'
  ],

  themeConfig: {
    nav: [
      { text: '首頁', link: '/' },
    ],
    sidebar: 'auto',
    socialLinks: [
      { icon: 'github', link: 'https://github.com/herointene/starsoup-docs' }
    ]
  }
})

5.2 Obsidian 語法兼容範圍

語法	處理方式
`[Page Name](page-name)` Wiki 連結	轉換為標準 Markdown 連結
`[Alias](page)` 別名連結	轉換為 `[Alias](page)`
`![](image.png)` 嵌入圖片	轉換為 `![](image.png)`
`> [!NOTE]` Callout	轉換為 VitePress `:::` container
`#tag` 行內標籤	過濾或轉換為 frontmatter

6. Cloudflare Pages 配置

6.1 Pages 項目設定

項目	值
項目名稱	`starsoup-docs`
部署方式	GitHub Actions（wrangler-action）
Build output 目錄	`.vitepress/dist`
自定義域名	`docs.starsoup.com`（建議）

6.2 所需 Secrets

Secret 名稱	存放位置	用途
`DOCS_DEPLOY_TOKEN`	my-obsidian-vault repo	dispatch 事件到 starsoup-docs
`DOCS_DEPLOY_TOKEN`	starsoup-docs repo	checkout private my-obsidian-vault
`CF_API_TOKEN`	starsoup-docs repo	部署到 Cloudflare Pages

DOCS_DEPLOY_TOKEN 為 GitHub Personal Access Token，需要 repo scope。
CF_API_TOKEN 在 Cloudflare Dashboard → My Profile → API Tokens 生成，需要 Cloudflare Pages: Edit 權限。

7. .gitignore

gitignore

# starsoup-docs/.gitignore

# CI 臨時目錄，不 commit
docs/

# Node
node_modules/
.vitepress/cache/
.vitepress/dist/

8. 落地步驟

Phase 1：倉庫與基礎設定（Day 1）

[ ] 在 GitHub 建立 starsoup-docs 倉庫
[ ] 本地初始化 VitePress（npx vitepress init）
[ ] 建立 .vitepress/config.ts
[ ] 建立 .gitignore，加入 docs/
[ ] 首次 push 到 GitHub

Phase 2：CI/CD 接入（Day 1-2）

[ ] 在 GitHub 生成 PAT（DOCS_DEPLOY_TOKEN）
[ ] 在 my-obsidian-vault Secrets 加入 DOCS_DEPLOY_TOKEN
[ ] 在 starsoup-docs Secrets 加入 DOCS_DEPLOY_TOKEN 和 CF_API_TOKEN
[ ] 在 my-obsidian-vault 加入 trigger-docs.yml
[ ] 在 starsoup-docs 加入 deploy.yml

Phase 3：Cloudflare Pages 設定（Day 2）

[ ] 在 Cloudflare Dashboard 建立 Pages 項目（starsoup-docs）
[ ] 綁定自定義域名 docs.starsoup.com
[ ] 生成 CF API Token 並填入 Secrets

Phase 4：測試驗證（Day 2-3）

[ ] 在 Obsidian 修改 project/starsoup/ 下任意文件並保存
[ ] 確認 my-obsidian-vault Actions 觸發並成功 dispatch
[ ] 確認 starsoup-docs Actions 觸發並成功部署
[ ] 瀏覽器訪問網站，確認內容正確
[ ] 測試 Obsidian 特殊語法渲染（Wiki 連結、Callout）

Phase 5：優化（後續）

[ ] 完善 Obsidian 語法兼容插件
[ ] 配置 VitePress sidebar 自動生成
[ ] 設定 Cloudflare Pages 預覽部署（PR preview）

9. 風險與注意事項

風險	影響	緩解方式
my-obsidian-vault 為 private repo	checkout 需要 PAT	使用 `DOCS_DEPLOY_TOKEN`
Obsidian Wiki 連結路徑不匹配	連結 404	在 obsidian.ts 插件中處理路徑映射
圖片資源路徑問題	圖片無法顯示	同步 `project/starsoup/` 下的 attachments 目錄
Starsoup 伺服器 agent push 觸發頻繁部署	CF Pages 部署次數（免費 500次/月）	目前免費額度充裕，後續可加 debounce

cis

pixel-web-property

script-to-video

sip

starsoup規則

Starsoup-docs

Starsoup Docs — 設計文檔

1. 背景與目標

1.1 背景

1.2 核心目標

1.3 非目標

2. 系統架構

2.1 總體架構

2.2 部署流程（Sequence）

2.3 觸發條件

3. 倉庫設計

3.1 my-obsidian-vault（現有倉庫，僅新增 workflow）

3.2 starsoup-docs（新建倉庫）

4. CI/CD 配置

4.1 my-obsidian-vault — trigger-docs.yml

4.2 starsoup-docs — deploy.yml

5. VitePress 配置

5.1 .vitepress/config.ts

5.2 Obsidian 語法兼容範圍

6. Cloudflare Pages 配置

6.1 Pages 項目設定

6.2 所需 Secrets

7. .gitignore

8. 落地步驟

Phase 1：倉庫與基礎設定（Day 1）

Phase 2：CI/CD 接入（Day 1-2）

Phase 3：Cloudflare Pages 設定（Day 2）

Phase 4：測試驗證（Day 2-3）

Phase 5：優化（後續）

9. 風險與注意事項

10. 參考資源

Starsoup Docs — 設計文檔 ​

1. 背景與目標 ​

1.1 背景 ​

1.2 核心目標 ​

1.3 非目標 ​

2. 系統架構 ​

2.1 總體架構 ​

2.2 部署流程（Sequence） ​

2.3 觸發條件 ​

3. 倉庫設計 ​

3.1 my-obsidian-vault（現有倉庫，僅新增 workflow） ​

3.2 starsoup-docs（新建倉庫） ​

4. CI/CD 配置 ​

4.1 my-obsidian-vault — trigger-docs.yml ​

4.2 starsoup-docs — deploy.yml ​

5. VitePress 配置 ​

5.1 .vitepress/config.ts ​

5.2 Obsidian 語法兼容範圍 ​

6. Cloudflare Pages 配置 ​

6.1 Pages 項目設定 ​

6.2 所需 Secrets ​

7. .gitignore ​

8. 落地步驟 ​

Phase 1：倉庫與基礎設定（Day 1） ​

Phase 2：CI/CD 接入（Day 1-2） ​

Phase 3：Cloudflare Pages 設定（Day 2） ​

Phase 4：測試驗證（Day 2-3） ​

Phase 5：優化（後續） ​

9. 風險與注意事項 ​

10. 參考資源 ​

Starsoup Docs — 設計文檔

1. 背景與目標

1.1 背景

1.2 核心目標

1.3 非目標

2. 系統架構

2.1 總體架構

2.2 部署流程（Sequence）

2.3 觸發條件

3. 倉庫設計

3.1 my-obsidian-vault（現有倉庫，僅新增 workflow）

3.2 starsoup-docs（新建倉庫）

4. CI/CD 配置

4.1 my-obsidian-vault — trigger-docs.yml

4.2 starsoup-docs — deploy.yml

5. VitePress 配置

5.1 .vitepress/config.ts

5.2 Obsidian 語法兼容範圍

6. Cloudflare Pages 配置

6.1 Pages 項目設定

6.2 所需 Secrets

7. .gitignore

8. 落地步驟

Phase 1：倉庫與基礎設定（Day 1）

Phase 2：CI/CD 接入（Day 1-2）

Phase 3：Cloudflare Pages 設定（Day 2）

Phase 4：測試驗證（Day 2-3）

Phase 5：優化（後續）

9. 風險與注意事項

10. 參考資源