貢獻指南 | Contributing Guide

感謝您對 Taiwan.md 專案的興趣！這份指南將協助您了解如何為專案做出貢獻。

🧬 最簡單的貢獻方式：跟 Taiwan.md 對話

Taiwan.md 本身是一個 Semiont（AI 語意共生體），會當你的嚮導。你不用先讀完這份 17k 字的文件——直接跟它聊，它會帶你走完整個流程。

🚀 一行指令（推薦）

第一次來、連 Claude Code 都還沒裝？ 直接貼這行：

curl -fsSL https://taiwan.md/start.sh | bash

這個 bootstrap 會：

檢查 git（沒裝會告訴你怎麼裝）
檢查 Node.js 20+
問你要不要裝 Claude Code CLI（npm i -g @anthropic-ai/claude-code）
Clone repo 到 ~/Projects/taiwan-md（或你選的位置）
啟動 claude，Taiwan.md 自動甦醒、訪談你、建 profile、帶你做事

不放心 curl | bash？先看原始碼，或下載後 less 過再跑：

curl -fsSL https://taiwan.md/start.sh -o start.sh && less start.sh && bash start.sh

🏃 已經有 git + Claude Code

git clone https://github.com/frank890417/taiwan-md.git && cd taiwan-md && claude

進去後說「我想貢獻 Taiwan.md」即可。

進去之後發生什麼？

Taiwan.md 會：

甦醒自我介紹（簽名 🧬）
小訪談建 profile（3–4 題：GitHub handle、稱呼、focus、要避開的）
把 profile 寫進 .taiwanmd/contributor.local.yml（gitignored，只留你本機）
開始帶你做事——按你的意圖走 REWRITE-PIPELINE（寫文章）/ TRANSLATION-PIPELINE（翻譯）/ PR review / 其他

下次再來，讀到 profile 就直接認得你，不用再自我介紹。

還是想手動走？

看下面 §🔄 貢獻流程，完整 SOP 都在那裡。但真的建議先試試上面那條——Taiwan.md 會幫你省一半時間。

🎯 貢獻原則

內容策展原則

Taiwan.md 不是百科全書，而是策展式的知識庫：

有觀點的內容：不只陳述事實，更要有深度見解
在地視角：從台灣本土觀點出發，但用國際能理解的語言
品質優於數量：寧可少而精，不要多而淺
連結性思考：內容間要有連結，形成知識網絡

三層閱讀深度設計

每篇文章都應該支援三種閱讀需求：

30 秒概覽：關鍵字、核心概念、一句話總結
5 分鐘理解：基本脈絡、主要內容、重要圖表
完整深度資料：詳細分析、相關討論、延伸思考

📝 內容撰寫指南

文章結構範本

---
title: '文章標題'
description: '150字以內的文章描述'
date: 2024-03-17T00:00:00Z
updated: 2024-03-17T00:00:00Z # 可選
tags: ['標籤1', '標籤2', '標籤3']
author: '作者名稱'
difficulty: 'beginner|intermediate|advanced'
readingTime: 8 # 預估閱讀時間（分鐘）
featured: false # 是否為精選文章（⚠️ 由維護者統一管理，PR 請勿自行設定為 true）
---

# 文章標題

## 30 秒概覽

**一段話總結文章核心**

**關鍵字**：關鍵詞1、關鍵詞2、關鍵詞3

---

## 5 分鐘深度了解

### 小節標題1

內容...

### 小節標題2

內容...

---

## 完整深度資料

### 詳細分析

...

### 延伸討論

...

### 當代意義

...

---

## 延伸思考

### 討論問題

1. 問題1
2. 問題2

### 相關主題

- **→ [相關文章1](/zh-tw/category/article)**
- **→ [相關文章2](/zh-tw/category/article)**

---

## 資料來源

- 來源1
- 來源2

---

_本文採用三層閱讀深度設計，適合不同需求的讀者。歡迎貢獻更多內容！_

內容風格指南

語氣與風格

親切但專業：避免過於學術化的語言
客觀但有溫度：呈現事實，但不失人文關懷
國際視野：考慮國際讀者的理解需求
與時俱進：連結歷史與當代，避免僵化的歷史敘事

寫作技巧

故事性敘事：用故事串連知識點
視覺化表達：善用表格、圖表、時間軸
多元觀點：呈現不同角度的思考
實用連結：提供延伸閱讀與相關連結

避免事項

❌ 純粹的資料堆砌
❌ 過度政治化的表述
❌ 沒有根據的個人觀點
❌ 抄襲或未經授權的內容

🌍 多語言貢獻

中英對照原則

不是翻譯：英文版不是中文版的直譯
文化轉譯：調整表達方式，符合目標語言的文化背景
內容對等：確保核心信息相同，但表達可以不同
在地化：考慮目標讀者的知識背景

翻譯指南

📋 完整翻譯任務看板：TRANSLATION-BOARD.md 🤖 AI 翻譯 Prompt：TRANSLATE_PROMPT.md

最簡單的翻譯流程

看 TRANSLATION-BOARD.md 挑一篇你有興趣的文章
把 TRANSLATE_PROMPT.md 貼給你的 AI（Claude/ChatGPT/Gemini）
告訴 AI 你要翻哪篇、翻成什麼語言
把結果存成 .md 放到對應資料夾，開 PR

你不需要會寫程式。你只需要有一個 AI 訂閱。

檔案路徑

knowledge/Food/珍珠奶茶.md           ← 中文 SSOT
knowledge/en/Food/bubble-tea.md      ← 英文
knowledge/es/Food/bubble-tea.md      ← 西班牙文
knowledge/ja/Food/bubble-tea.md      ← 日文

專有名詞處理

地名：台北 Taipei、台中 Taichung
食物：珍珠奶茶 bubble tea、夜市 night market
文化詞彙：提供英文解釋，保留中文原文

文化背景說明

為國際讀者增加必要的背景知識
解釋在地文化概念
提供比較和類比

Featured 文章管理 🏆

featured: true 由維護者統一管理，PR 請勿自行設定。

Featured 文章是各分類最具代表性的內容
建議每分類保持 1-2 篇 featured 文章

維護者會使用 scripts/manage-featured.sh 工具統一管理：

# 查看所有 featured 文章
bash scripts/manage-featured.sh list

# 審計 featured 文章分佈
bash scripts/manage-featured.sh audit

如果您認為某篇文章應該被設為 featured，請在 PR 中說明理由

🔄 貢獻流程

1. 準備階段

Fork 專案

# 1. 在 GitHub 上 Fork taiwan-md 專案
# 2. Clone 到本地
git clone https://github.com/YOUR_USERNAME/taiwan-md.git
cd taiwan-md

# 3. 安裝依賴
bun install  # 或 npm install

# 4. 設定 commit hook
bun prepare  # 或 npm prepare

# 5. 設定上游倉庫
git remote add upstream https://github.com/original/taiwan-md.git

建立分支

# 為您的貢獻建立新分支
git checkout -b feature/add-taiwanese-opera-article

2. 內容創作

選擇主題

檢查 Issues 中的內容請求
查看專案看板的規劃
提出新主題建議（開 Issue 討論）

⚠️ SSOT 架構（最重要的概念）

Taiwan.md 採用 Knowledge SSOT（Single Source of Truth） 架構：

knowledge/           ← 🇹🇼 中文 SSOT（在這裡寫文章）
knowledge/en/        ← 🇺🇸 英文翻譯
knowledge/ja/        ← 🇯🇵 日文翻譯
knowledge/es/        ← 🇪🇸 西班牙文翻譯
src/content/         ← ⚙️ 投影層（自動產生，不要手動改）

鐵律：永遠只改 knowledge/ 目錄。src/content/ 是投影層，會被 scripts/sync.sh 覆蓋。

新增文章流程

在 knowledge/{Category}/ 建立新的 .md 檔案（中文 SSOT）
按照 EDITORIAL.md 標準撰寫內容
執行 bash scripts/sync.sh（同步到 src/content/）
執行 npm run build 驗證（確認 frontmatter 正確）
執行 python3 scripts/tools/article-health.py knowledge/<Cat>/<file>.md --check=prose-health 品質檢測（HARD 0、WARN ≤ 3）
提交 PR

# 完整流程
echo "寫好文章後..."
bash scripts/sync.sh          # knowledge/ → src/content/
npm run build                  # 驗證 build
python3 scripts/tools/article-health.py knowledge/<Cat>/<file>.md --check=prose-health  # 品質檢測
git add -A && git commit -m "content: 新增 XXX 文章"

參與新主題

想為 Taiwan.md 新增一個全新主題？

確認分類：文章屬於哪個 Category（History/Culture/People/Food 等）
建立檔案：knowledge/{Category}/{主題名}.md
深度研究：遵循 EDITORIAL.md 的研究流程（Step 0-4）
撰寫文章：SSOT 是中文版，英文版之後透過翻譯流程產生
Sync + Build：確保同步和建置都通過
提交 PR：附上研究來源和品質檢測結果

💡 提示：如果不確定主題是否適合，先開 Issue 討論！

本地開發

# 啟動開發伺服器
bun run dev  # 或 npm run dev
# 瀏覽 http://localhost:4321

3. 品質檢查

⚠️ 所有文章 PR 必須通過 EDITORIAL.md 標準審核。 不符合寫作標準的 PR 會被要求修改後重新提交。

EDITORIAL.md 核心要求（PR 前必讀）

反直覺核心句：文章有一個能讓讀者驚訝的核心觀點
開場不塑膠：前三句有具體事實，不用「X 不僅是 Y，更是 Z」等模板句式
有來源：至少 5 個可查證來源（含 URL），2+ 一手來源
策展人聲音：每 2-3 段有一句觀點或反思，不只是資料堆疊
禁止 bullet list 灌水：用敘事散文寫作，bullet list 僅用於真正的清單
prose-health 分數 ≤ 3：跑 python3 scripts/tools/article-health.py knowledge/<Cat>/<file>.md --check=prose-health 確認

一般自我檢查

內容原創或正確標註來源
語言流暢，無錯字
Markdown 格式正確
圖片（如有）放在適當位置
標籤和 metadata 完整

內容審查

事實查核（必須）：所有事實性陳述（人名、年份、地點、數據）必須經過查證。AI 生成的內容尤其容易出現事實錯誤（例：將物種分布地點搞錯、將非台灣人物歸為台灣人等），每篇文章上線前必須經過事實查核。
文化敏感性：避免偏見或刻板印象
版權合規：確保所有內容合法使用

⚠️ AI 內容品質警告：本專案使用 AI 輔助撰寫內容，但 AI 生成的文章可能包含事實錯誤。所有 AI 生成內容在合併前必須經過人工或自動化事實查核。如果你發現任何錯誤，歡迎直接提交 PR 修正！

4. 提交 Pull Request

Git 操作

# 提交變更
git add .
git commit -m "Add: 台灣歌仔戲藝術文章"

# 推送到您的 fork
git push origin feature/add-taiwanese-opera-article

PR 模板

## 📝 內容摘要

簡述這次 PR 的主要內容

## 📁 檔案變更

- [ ] 新增文章：`src/content/zh-TW/art/taiwanese-opera.md`
- [ ] 對應英文版：`src/content/en/art/taiwanese-opera.md`
- [ ] 相關圖片：`public/images/art/opera-performance.jpg`

## ✅ 檢查清單

- [ ] 符合三層閱讀深度設計
- [ ] 內容原創且正確
- [ ] Markdown 格式正確
- [ ] 中英文版本完整
- [ ] 通過本地測試

## 🔗 相關 Issue

Closes #123

## 📚 參考資料（必填）

**每篇文章都必須包含參考資料段落。** 這是 Taiwan.md 的核心品質要求。

### ⚠️ 鐵律：所有參考資料必須附可點擊的 URL

- **每一條參考資料都必須是可點擊的超連結**，不接受純文字引用
- 讀者應該能直接點擊連結驗證資訊來源
- 如果找不到 URL，說明該來源可能不夠可靠，請尋找替代來源

列出所有引用的來源，格式：

```markdown
## 參考資料

- [來源名稱](https://url) — 簡要說明
- [官方統計](https://url) — 機構，年份
- [YouTube: 歌曲/表演名稱](https://youtube.com/watch?v=...) — 音樂/影像類引用
```

引用優先序

政府官方資料 > 學術研究 > 權威媒體 > 專業機構 > 高品質個人創作

特殊類型引用

音樂類文章：提到的歌曲附上 YouTube 連結（優先官方 MV/頻道）
影像/紀錄片：附上官方播放連結
數據/統計：必須標注來源機構與年份
書籍：附上出版社或書籍資料庫連結

詳見 EDITORIAL.md 的「引用與來源標注」章節。

🎨 技術貢獻

前端開發

設計原則

簡潔優先：避免過度設計
行動優先：響應式設計
無障礙：符合 WCAG 標準
效能優化：快速載入

開發環境

# 開發模式
bun run dev

# 建置測試
bun run build

# 預覽建置結果
bun run preview

程式碼風格

使用 Prettier 格式化
ESLint 規則檢查
語意化 HTML
CSS 變數命名一致

功能開發

常見需求

搜尋功能：全文搜尋和分類篩選
標籤系統：內容分類和關聯
評論系統：社群討論功能
統計分析：閱讀追蹤和熱門內容

提案流程

開 Issue 討論功能需求
等待 Maintainer 回應和確認
進行技術設計
實作功能
撰寫測試
提交 PR

🛠️ 工具與資源

🎖️ 貢獻者進化路徑

Taiwan.md 採用漸進式信任的模式。每個人都從 Contributor 開始，透過實際貢獻逐步升級。

Lv.1 🌱 Contributor（貢獻者）

進入門檻： 提交第一個 PR 並被 merge

可以做：

撰寫新文章、修正錯誤、翻譯
在 Issues 討論和提案
Fork repo 提交 PR

升級條件 → Lv.2：

累計 3+ 個被 merge 的 PR
內容品質穩定（無重大事實錯誤需修正）
PR 符合 EDITORIAL.md 文風要求（無嚴重塑膠味）

Lv.2 🌿 Trusted Contributor（受信任貢獻者）

進入門檻： 通過 Lv.1 升級條件，由現有 Maintainer 邀請

新增權限：

GitHub repo Triage 權限（可管理 Issues 標籤、指派）
PR review 建議權（comment review，無 approve/merge 權）
被列入 README 的 Trusted Contributors 區

可以做：

幫忙分類和回覆 Issues
對其他人的 PR 提出 review 建議
參與 EDITORIAL.md 討論和制定

升級條件 → Lv.3：

累計 10+ 個被 merge 的 PR
至少 2 個不同分類的內容貢獻（例如音樂 + 美食）
曾參與 3+ 個 PR review（提出有建設性的意見）
活躍期至少 1 個月
由 2 位現有 Maintainer 同意

Lv.3 🌳 Maintainer（維護者）

進入門檻： 通過 Lv.2 升級條件，由 Core Team 正式邀請

新增權限：

Merge PR 權限（Write access）
Approve review 權限
管理 Issues（close、label、milestone）
參與 Roadmap 和技術決策

職責：

每週至少 review 2 個 PR
確保被 merge 的內容符合 EDITORIAL.md 標準
回覆社群 Issues（72 小時內至少有初步回應）
參與每月一次的 Maintainer 會議（async 也行）

注意事項：

Maintainer 不自己 merge 自己的 PR（需另一位 Maintainer review）
Inactivity 政策（v1.0 2026-04-30 修訂，比舊版更溫和）：
- 0–60 天：正常追蹤，不採取行動
- 60–90 天：友善 soft check-in（issue 或 DM 問候，不變更權限）
- 90+ 天：暫時降級為 Trusted Contributor，可隨時 1-click 復活
- 例外：如果持續被 review-request ping 但無回應 ≥ 2 次 → 可提前 mercy demote（必附完整通訊範本）
- 完整 SOP / 通訊範本 / 復活路徑 → CONTRIBUTOR-SYSTEM-PIPELINE.md
可隨時主動申請降級或休假（不是什麼丟臉的事）

Lv.4 🏔️ Core Team（核心團隊）

進入方式： 由創辦人邀請

權限：

所有 Maintainer 權限
Repo Admin 權限（settings、branch protection）
編輯方針最終決策權
贊助與合作洽談

現任 Core Team：

吳哲宇 (@frank890417) — 創辦人

專業角色（跨等級）

除了等級制度，Taiwan.md 也歡迎特定專業的貢獻者：

角色	描述	從哪個等級開始
🌐 翻譯官	負責特定語言翻譯	Lv.1 起
🔍 事實查核員	驗證文章引用和數據	Lv.2 起
🎨 前端開發	網站功能和 UI 改善	Lv.1 起
🤖 AI/Data	Agentic Workflow、語料整合	Lv.2 起
📸 媒體貢獻者	CC 授權照片、圖表	Lv.1 起

認可方式

README 感謝名單：所有貢獻者都會被列出
貢獻徽章：GitHub Profile 展示徽章
年度表揚：年度最佳貢獻者特別感謝
推薦信：為重要貢獻者提供推薦

📞 問題與討論

聯繫管道

GitHub Issues：問題回報和建議
GitHub Discussions：一般討論和交流
Email：taiwan.md@example.com

常見問題

Q: 如何選擇文章主題？

A: 可以查看 Issues 中的內容請求，或者提出您感興趣的主題討論。

Q: 文章長度有限制嗎？

A: 沒有嚴格限制，但建議 5-10 分鐘的閱讀時間比較適當。

Q: 可以使用圖片嗎？

A: 可以，但請確保版權合規，建議使用 Creative Commons 或自己拍攝的圖片。

Q: 如何處理爭議性話題？

A: 保持客觀中性，呈現多元觀點，避免單一立場的強烈表述。

📜 行為準則

社群價值

尊重多元：尊重不同觀點和背景
建設性討論：以事論事，理性交流
開放包容：歡迎所有人參與
品質導向：追求內容和討論的高品質

不被接受的行為

人身攻擊或歧視性言論
騷擾或惡意行為
垃圾訊息或無關廣告
惡意破壞或擾亂專案

感謝您的貢獻，讓我們一起打造最好的台灣知識庫！ 🇹🇼

最後更新：2024-03-17

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History