Taiwan Md Knowledge Base

Taiwan.md Knowledge Base

Skill by ara.so — Daily 2026 Skills collection.

Taiwan.md is an open-source, AI-native knowledge base about Taiwan built with Astro v5. It uses a Single Source of Truth (SSOT) architecture where all content lives in the knowledge/ directory as Markdown files, and the website is a build-time projection. Features include bilingual support (Traditional Chinese as default + English), an interactive D3.js knowledge graph, and 96+ curated articles across 12 categories.

Installation & Setup

Prerequisites

• Node.js 18+
• npm or pnpm

Clone and Install

git clone https://github.com/frank890417/taiwan-md.gitcd taiwan-mdnpm install

Development Server

npm run dev# Site available at http://localhost:4321

Build & Preview

npm run buildnpm run preview

Sync Knowledge to Content

bash scripts/sync.sh# Copies knowledge/ → src/content/ for Astro build

Project Architecture

taiwan-md/├── knowledge/               ← SSOT: ALL content lives here│   ├── History/             ← Chinese articles + _Hub.md│   ├── Geography/│   ├── Culture/│   ├── Food/│   ├── Art/│   ├── Music/│   ├── Technology/│   ├── Nature/│   ├── People/│   ├── Society/│   ├── Economy/│   ├── Lifestyle/│   ├── About/               ← Meta content│   └── en/                  ← English translations (mirrors zh-TW)│       ├── History/│       ├── Geography/│       └── ...├── scripts/│   └── sync.sh              ← Syncs knowledge/ → src/content/├── src/│   ├── pages/               ← Astro pages│   ├── layouts/             ← Shared layouts│   └── content/             ← Build-time projection (DO NOT EDIT)├── public/│   └── images/wiki/         ← Cached Wikimedia Commons images└── docs/                    ← Architecture & roadmap docs

Critical rule: Never edit files in src/content/ directly. Always edit knowledge/ and run scripts/sync.sh.

Content Structure

The 12 Categories

Article File Naming

knowledge/├── Food/│   ├── _Hub.md              ← Category hub page (literary overview)│   ├── bubble-tea.md        ← Individual article (zh-TW)│   └── beef-noodle.md└── en/    └── Food/        ├── _Hub.md          ← English hub page        ├── bubble-tea.md    ← English translation        └── beef-noodle.md

Writing Articles

Chinese Article Template (knowledge/[Category]/article-slug.md)

---title: 珍珠奶茶description: 台灣最具代表性的飲料文化，從夜市攤車到全球連鎖，珍珠奶茶如何征服世界。category: fooddate: 2024-01-15tags: [飲食文化, 台灣之光, 夜市]image: /images/wiki/bubble-tea-abc123.jpgimageCaption: 台灣珍珠奶茶 | Wikimedia Commons | CC BY-SA 4.0sources:  - title: 珍珠奶茶的起源考證    url: https://example.com/boba-origin  - title: 台灣飲料市場報告    url: https://example.com/beverage-report---
## 30 秒認識
珍珠奶茶（波霸奶茶）誕生於 1980 年代台灣，現已成為全球年產值超過 30 億美元的飲料產業。
## 深度閱讀
### 起源爭議
台南翰林茶館與台中春水堂都聲稱是珍珠奶茶的發明者...
### 全球擴張
2010 年代，珍珠奶茶席捲歐美亞各大城市...
## 為什麼重要
珍珠奶茶不只是一杯飲料，它是台灣軟實力的最佳代言人——在沒有邦交的地方，台灣味道先到了。
## 參考資料
- [珍珠奶茶的起源考證](https://example.com/boba-origin)- [台灣飲料市場報告](https://example.com/beverage-report)

English Article Template (knowledge/en/[Category]/article-slug.md)

---title: Bubble Teadescription: Taiwan's most iconic beverage culture — how boba conquered the world from night market stalls to global chains.category: fooddate: 2024-01-15tags: [food culture, taiwan pride, night market]image: /images/wiki/bubble-tea-abc123.jpgimageCaption: Taiwanese Bubble Tea | Wikimedia Commons | CC BY-SA 4.0sources:  - title: Origins of Bubble Tea    url: https://example.com/boba-origin  - title: Taiwan Beverage Market Report    url: https://example.com/beverage-report---
## 30-Second Overview
Bubble tea (boba) was born in 1980s Taiwan and has grown into a global industry worth over $3 billion annually.
## Deep Dive
### The Origin Debate
Both Hanlin Tea Room in Tainan and Chun Shui Tang in Taichung claim to have invented bubble tea...
### Global Expansion
In the 2010s, bubble tea swept across cities in Europe, America, and Asia...
## Why This Matters
Bubble tea isn't just a drink — it's Taiwan's finest soft power ambassador. Where there's no diplomatic recognition, Taiwanese flavor arrived first.
## References
- [Origins of Bubble Tea](https://example.com/boba-origin)- [Taiwan Beverage Market Report](https://example.com/beverage-report)

Hub Page Template (knowledge/[Category]/_Hub.md)

---title: 美食titleEn: Fooddescription: 台灣的飲食文化是移民歷史、地理環境與創意精神的完美結晶。category: food---
## 關於這個分類
台灣是一個以食物說故事的地方...
## 精選文章
這個分類收錄了台灣飲食文化最具代表性的面向...

Frontmatter Reference

Required Fields

---title: "文章標題"           # Display titledescription: "一句話說明"   # Meta description (150 chars max)category: food             # Must match one of 12 category slugsdate: 2024-01-15           # ISO date format---

Optional Fields

---tags: [tag1, tag2]         # Array of tags for knowledge graphimage: /images/wiki/...    # Must be from Wikimedia Commons cacheimageCaption: "..."        # Attribution: Title | Source | Licensesources:                   # REQUIRED: clickable URLs, no plain-text refs  - title: "Source Name"    url: https://...---

Adding Images (Wikimedia Commons Policy)

All images must be from Wikimedia Commons with verified CC licenses. Cache them locally:

# Download and cache a Wikimedia image# Images are stored with MD5-hashed filenamescurl -o public/images/wiki/$(echo "filename.jpg" | md5sum | cut -d' ' -f1).jpg \  "https://commons.wikimedia.org/wiki/Special:FilePath/Taiwan_landscape.jpg"

Image attribution format in frontmatter:

imageCaption: "Description | Wikimedia Commons | CC BY-SA 4.0"

Knowledge Graph Integration

Articles automatically appear in the D3.js knowledge graph at /graph. Nodes are created from articles; edges are created from shared tags and cross-references.

Linking Articles

Reference other articles within content using relative paths:

台灣的[半導體產業](/technology/tsmc)是台積電...
See also: [Bubble Tea](/food/bubble-tea) for more on Taiwan's soft power.

Tagging for Graph Connections

Use consistent tags to create knowledge graph bridges:

# Both articles tagged [democratic transition] will be connectedtags: [democratic transition, civil society, 1990s]

Sync Workflow

After editing any file in knowledge/, always sync before building:

# 1. Edit contentvim knowledge/Food/new-article.mdvim knowledge/en/Food/new-article.md
# 2. Sync to src/content/bash scripts/sync.sh
# 3. Verify buildnpm run build
# 4. Previewnpm run preview

Three-Layer Depth Pattern

Every article should follow this structure for AI-readability and varied reading levels:

## 30 秒認識 / 30-Second Overview[2-3 sentences, the essential fact]
## 深度閱讀 / Deep Dive### Subsection 1[Detailed exploration with data]
### Subsection 2[Historical context or comparison]
## 為什麼重要 / Why This Matters[Curatorial perspective — answer "why should the world care?"]
## 參考資料 / References[Clickable URLs only — no plain-text citations]

Contributing via PR

Full PR Workflow

# 1. Fork and clonegit clone https://github.com/YOUR_USERNAME/taiwan-md.gitcd taiwan-md
# 2. Create branchgit checkout -b add/food/scallion-pancake
# 3. Add zh-TW articlecat > knowledge/Food/scallion-pancake.md << 'EOF'---title: 蔥抓餅description: ...category: fooddate: 2024-01-20sources:  - title: Source    url: https://...---Content here...EOF
# 4. Add English translationmkdir -p knowledge/en/Foodcat > knowledge/en/Food/scallion-pancake.md << 'EOF'---title: Scallion Pancake...EOF
# 5. Sync and testbash scripts/sync.shnpm run build
# 6. Commit and PRgit add knowledge/git commit -m "feat(food): add scallion pancake article (zh+en)"git push origin add/food/scallion-pancake

Commit Message Convention

feat(category): add [article name] article (zh+en)fix(category): correct [article name] factual errori18n(category): add English translation for [article name]feat(graph): add knowledge graph connections for [topic]

AI-Native Features

llms.txt

The site exposes /llms.txt for AI consumption. When writing content, use structured headers that AI can parse:

# Title
**Key fact:** One-sentence essential truth.
## Context...
## Significance...

Meta AI Summary Tag

Pages include <meta ai-summary> — write descriptions that work as standalone AI context:

description: "台積電（TSMC）生產全球90%最先進晶片，是台灣的「矽盾」——台灣的地緣政治生存策略。"

Astro Page Patterns

Category Page (src/pages/[category].astro)

---import { getCollection } from 'astro:content';
const category = 'food';const articles = await getCollection('knowledge', ({ data }) =>  data.category === category);---
<ul>  {articles.map(article => (    <li>      <a href={`/${category}/${article.slug}`}>{article.data.title}</a>      <p>{article.data.description}</p>    </li>  ))}</ul>

Bilingual Route Pattern

/food/bubble-tea        ← zh-TW (default)/en/food/bubble-tea     ← English

Content Quality Checklist

Before submitting a PR, verify:

• Both knowledge/[Category]/article.md (zh-TW) and knowledge/en/[Category]/article.md (en) exist
• All sources entries have clickable url fields (no plain-text-only references)
• Article follows three-layer depth: 30-sec → deep dive → why it matters
• Images sourced from Wikimedia Commons with proper imageCaption attribution
• category slug matches one of the 12 valid categories exactly
• bash scripts/sync.sh && npm run build completes without errors
• Factual claims are verified against cited sources

Troubleshooting

Build fails after adding article

# Check frontmatter syntaxcat knowledge/Food/my-article.md | head -20
# Common issue: missing required fields# Ensure title, description, category, date are all present
# Re-sync and rebuildbash scripts/sync.shnpm run build 2>&1 | grep ERROR

Article not appearing in knowledge graph

# Ensure tags array is populated# Check category slug matches exactly (case-sensitive)# Verify sync was run after editingbash scripts/sync.sh

English article not showing at /en/...

# Verify file exists at correct pathls knowledge/en/Food/my-article.md
# Check category field matches zh-TW article exactlygrep "category:" knowledge/Food/my-article.mdgrep "category:" knowledge/en/Food/my-article.md

Images not loading

# Images must be cached locally in public/images/wiki/ls public/images/wiki/
# Verify frontmatter path starts with /images/wiki/grep "image:" knowledge/Food/my-article.md# Should be: image: /images/wiki/filename-hash.jpg

Sync script permission error

chmod +x scripts/sync.shbash scripts/sync.sh

Resources

• Live site: https://taiwan.md
• Knowledge graph: https://taiwan.md/graph
• Contribute guide: https://taiwan.md/contribute
• llms.txt: https://taiwan.md/llms.txt
• License: CC BY-SA 4.0 (content) + MIT (code)
• Contact: [email protected]