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 年代，珍珠奶茶席捲歐美亞各大城市...

為什麼重要珍珠奶茶不只是一杯飲料，它是台灣軟實力的最佳代言人——在沒有邦交的地方，台灣味道先到了。

參考資料

珍珠奶茶的起源考證 - 台灣飲料市場報告 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 - Taiwan Beverage Market 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: 台灣的半導體產業是台積電... See also: 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 );

{article.data.title}
{article.data.description}

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

taiwan-md-knowledge-base

安装