From aradotso-trending-skills-37
Provides context for Taiwan.md, an Astro v5 knowledge base with bilingual Markdown SSOT and D3.js graph. Use to add articles, contribute content, setup locally, or translate to English.
npx claudepluginhub joshuarweaver/cascade-ai-ml-agents-misc-1 --plugin aradotso-trending-skills-37This skill uses the workspace's default tool permissions.
> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.
Guides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Guides building MCP servers enabling LLMs to interact with external services via tools. Covers best practices, TypeScript/Node (MCP SDK), Python (FastMCP).
Generates original PNG/PDF visual art via design philosophy manifestos for posters, graphics, and static designs on user request.
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.
git clone https://github.com/frank890417/taiwan-md.git
cd taiwan-md
npm install
npm run dev
# Site available at http://localhost:4321
npm run build
npm run preview
bash scripts/sync.sh
# Copies knowledge/ → src/content/ for Astro build
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.
| 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 |
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
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)
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)
knowledge/[Category]/_Hub.md)---
title: 美食
titleEn: Food
description: 台灣的飲食文化是移民歷史、地理環境與創意精神的完美結晶。
category: food
---
## 關於這個分類
台灣是一個以食物說故事的地方...
## 精選文章
這個分類收錄了台灣飲食文化最具代表性的面向...
---
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
---
---
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://...
---
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"
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.
Reference other articles within content using relative paths:
台灣的[半導體產業](/technology/tsmc)是台積電...
See also: [Bubble Tea](/food/bubble-tea) for more on Taiwan's soft power.
Use consistent tags to create knowledge graph bridges:
# Both articles tagged [democratic transition] will be connected
tags: [democratic transition, civil society, 1990s]
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
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]
# 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
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]
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
...
Pages include <meta ai-summary> — write descriptions that work as standalone AI context:
description: "台積電(TSMC)生產全球90%最先進晶片,是台灣的「矽盾」——台灣的地緣政治生存策略。"
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>
/food/bubble-tea ← zh-TW (default)
/en/food/bubble-tea ← English
Before submitting a PR, verify:
knowledge/[Category]/article.md (zh-TW) and knowledge/en/[Category]/article.md (en) existsources entries have clickable url fields (no plain-text-only references)imageCaption attributioncategory slug matches one of the 12 valid categories exactlybash scripts/sync.sh && npm run build completes without errors# 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
# Ensure tags array is populated
# Check category slug matches exactly (case-sensitive)
# Verify sync was run after editing
bash scripts/sync.sh
# 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 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
chmod +x scripts/sync.sh
bash scripts/sync.sh