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.git
cd taiwan-md
npm install

Development Server

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

Build & Preview

npm run build
npm 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

Slug	Chinese	English
history	歷史	History
geography	地理	Geography
culture	文化	Culture
food	美食	Food
art	藝術	Art
music	音樂	Music
technology	科技	Technology
nature	自然	Nature
people	人物	People
society	社會	Society
economy	經濟	Economy
lifestyle	生活	Lifestyle

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: food
date: 2024-01-15
tags: [飲食文化, 台灣之光, 夜市]
image: /images/wiki/bubble-tea-abc123.jpg
imageCaption: 台灣珍珠奶茶 | Wikimedia Commons | CC BY-SA 4.0
sources:
  - 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 Tea
description: Taiwan's most iconic beverage culture — how boba conquered the world from night market stalls to global chains.
category: food
date: 2024-01-15
tags: [food culture, taiwan pride, night market]
image: /images/wiki/bubble-tea-abc123.jpg
imageCaption: Taiwanese Bubble Tea | Wikimedia Commons | CC BY-SA 4.0
sources:
  - 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: Food
description: 台灣的飲食文化是移民歷史、地理環境與創意精神的完美結晶。
category: food
---

## 關於這個分類

台灣是一個以食物說故事的地方...

## 精選文章

這個分類收錄了台灣飲食文化最具代表性的面向...

---

Frontmatter Reference

Required Fields

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

Optional Fields

---
tags: [tag1, tag2]         # Array of tags for knowledge graph
image: /images/wiki/...    # Must be from Wikimedia Commons cache
imageCaption: "..."        # Attribution: Title | Source | License
sources:                   # 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 filenames
curl -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 connected
tags: [democratic transition, civil society, 1990s]

---

Sync Workflow

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

# 1. Edit content
vim knowledge/Food/new-article.md
vim knowledge/en/Food/new-article.md

# 2. Sync to src/content/
bash scripts/sync.sh

# 3. Verify build
npm run build

# 4. Preview
npm 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 clone
git clone https://github.com/YOUR_USERNAME/taiwan-md.git
cd taiwan-md

# 2. Create branch
git checkout -b add/food/scallion-pancake

# 3. Add zh-TW article
cat > knowledge/Food/scallion-pancake.md << 'EOF'
---
title: 蔥抓餅
description: ...
category: food
date: 2024-01-20
sources:
  - title: Source
    url: https://...
---
Content here...
EOF

# 4. Add English translation
mkdir -p knowledge/en/Food
cat > knowledge/en/Food/scallion-pancake.md << 'EOF'
---
title: Scallion Pancake
...
EOF

# 5. Sync and test
bash scripts/sync.sh
npm run build

# 6. Commit and PR
git 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 error
i18n(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 syntax
cat knowledge/Food/my-article.md | head -20

# Common issue: missing required fields
# Ensure title, description, category, date are all present

# Re-sync and rebuild
bash scripts/sync.sh
npm 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 editing
bash scripts/sync.sh

English article not showing at /en/...

# Verify file exists at correct path
ls knowledge/en/Food/my-article.md

# Check category field matches zh-TW article exactly
grep "category:" knowledge/Food/my-article.md
grep "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.sh
bash 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: cheyu.wu@monoame.com