Back to Details

taiwan-md-knowledge-base

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Taiwan.md Knowledge Base

Taiwan.md 知识库

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.
由ara.so提供的技能内容 — 2026每日技能合集。
Taiwan.md是一个基于Astro v5构建的、面向台湾的开源AI原生知识库。它采用单一数据源（SSOT）架构，所有内容都以Markdown文件形式存储在
knowledge/
目录中，网站则是构建时的投影产物。功能包括双语支持（默认繁体中文 + 英文）、交互式D3.js知识图谱，以及涵盖12个分类的96+篇精选文章。

Installation & Setup

安装与设置

Prerequisites

前置要求

  • Node.js 18+
  • npm or pnpm
  • Node.js 18+
  • npm 或 pnpm

Clone and Install

克隆并安装

bash
git clone https://github.com/frank890417/taiwan-md.git
cd taiwan-md
npm install
bash
git clone https://github.com/frank890417/taiwan-md.git
cd taiwan-md
npm install

Development Server

开发服务器

bash
npm run dev
bash
npm run dev

Site available at http://localhost:4321

站点可访问地址：http://localhost:4321

undefined
undefined

Build & Preview

构建与预览

bash
npm run build
npm run preview
bash
npm run build
npm run preview

Sync Knowledge to Content

将知识库内容同步到站点内容

bash
bash scripts/sync.sh
bash
bash scripts/sync.sh

Copies knowledge/ → src/content/ for Astro build

将knowledge/目录内容复制到src/content/目录，用于Astro构建


---

---

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
.
taiwan-md/
├── knowledge/               ← SSOT: 所有内容都存储在此处
│   ├── History/             ← 中文文章 + _Hub.md
│   ├── Geography/
│   ├── Culture/
│   ├── Food/
│   ├── Art/
│   ├── Music/
│   ├── Technology/
│   ├── Nature/
│   ├── People/
│   ├── Society/
│   ├── Economy/
│   ├── Lifestyle/
│   ├── About/               ← 元内容
│   └── en/                  ← 英文翻译版本（镜像繁体中文目录结构）
│       ├── History/
│       ├── Geography/
│       └── ...
├── scripts/
│   └── sync.sh              ← 将knowledge/同步到src/content/
├── src/
│   ├── pages/               ← Astro页面
│   ├── layouts/             ← 共享布局
│   └── content/             ← 构建时投影产物（请勿直接编辑）
├── public/
│   └── images/wiki/         ← 缓存的Wikimedia Commons图片
└── docs/                    ← 架构与路线图文档
重要规则： 请勿直接编辑
src/content/
目录下的文件。请始终在
knowledge/
目录中编辑内容，然后运行
scripts/sync.sh
脚本。

Content Structure

内容结构

The 12 Categories

12个分类

SlugChineseEnglish
history
歷史History
geography
地理Geography
culture
文化Culture
food
美食Food
art
藝術Art
music
音樂Music
technology
科技Technology
nature
自然Nature
people
人物People
society
社會Society
economy
經濟Economy
lifestyle
生活Lifestyle
标识中文英文
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
knowledge/
├── Food/
│   ├── _Hub.md              ← 分类主页（概述性内容）
│   ├── bubble-tea.md        ← 单篇文章（繁体中文）
│   └── beef-noodle.md
└── en/
    └── Food/
        ├── _Hub.md          ← 英文分类主页
        ├── bubble-tea.md    ← 英文翻译版本
        └── beef-noodle.md

Writing Articles

撰写文章

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

中文文章模板（
knowledge/[Category]/article-slug.md
）

markdown
---
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
---
markdown
---
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 秒認識

30 秒認識

珍珠奶茶（波霸奶茶）誕生於 1980 年代台灣，現已成為全球年產值超過 30 億美元的飲料產業。
珍珠奶茶（波霸奶茶）誕生於 1980 年代台灣，現已成為全球年產值超過 30 億美元的飲料產業。

深度閱讀

深度閱讀

起源爭議

起源爭議

台南翰林茶館與台中春水堂都聲稱是珍珠奶茶的發明者...
台南翰林茶館與台中春水堂都聲稱是珍珠奶茶的發明者...

全球擴張

全球擴張

2010 年代，珍珠奶茶席捲歐美亞各大城市...
2010 年代，珍珠奶茶席捲歐美亞各大城市...

為什麼重要

為什麼重要

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

參考資料

參考資料

undefined
undefined

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

英文文章模板（
knowledge/en/[Category]/article-slug.md
）

markdown
---
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
---
markdown
---
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

30-Second Overview

Bubble tea (boba) was born in 1980s Taiwan and has grown into a global industry worth over $3 billion annually.
Bubble tea (boba) was born in 1980s Taiwan and has grown into a global industry worth over $3 billion annually.

Deep Dive

Deep Dive

The Origin Debate

The Origin Debate

Both Hanlin Tea Room in Tainan and Chun Shui Tang in Taichung claim to have invented bubble tea...
Both Hanlin Tea Room in Tainan and Chun Shui Tang in Taichung claim to have invented bubble tea...

Global Expansion

Global Expansion

In the 2010s, bubble tea swept across cities in Europe, America, and Asia...
In the 2010s, bubble tea swept across cities in Europe, America, and Asia...

Why This Matters

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.
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

References

undefined
undefined

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

分类主页模板（
knowledge/[Category]/_Hub.md
）

markdown
---
title: 美食
titleEn: Food
description: 台灣的飲食文化是移民歷史、地理環境與創意精神的完美結晶。
category: food
---
markdown
---
title: 美食
titleEn: Food
description: 台灣的飲食文化是移民歷史、地理環境與創意精神的完美結晶。
category: food
---

關於這個分類

關於這個分類

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

精選文章

精選文章

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

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

---

Frontmatter Reference

前置元数据参考

Required Fields

必填字段

yaml
---
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
---
yaml
---
title: "文章標題"           # 显示标题
description: "一句話說明"   # 元描述（最多150字符）
category: food             # 必须匹配12个分类标识之一
date: 2024-01-15           # ISO日期格式
---

Optional Fields

可选字段

yaml
---
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://...
---
yaml
---
tags: [tag1, tag2]         # 用于知识图谱的标签数组
image: /images/wiki/...    # 必须来自Wikimedia Commons缓存
imageCaption: "..."        # 署名格式：标题 | 来源 | 许可证
sources:                   # 必填：可点击的URL，不接受纯文本参考
  - title: "Source Name"
    url: https://...
---

Adding Images (Wikimedia Commons Policy)

添加图片（Wikimedia Commons政策）

All images must be from Wikimedia Commons with verified CC licenses. Cache them locally:
bash
undefined
所有图片必须来自Wikimedia Commons且拥有已验证的CC许可证。请在本地缓存：
bash
undefined

Download and cache a Wikimedia image

下载并缓存Wikimedia图片

Images are stored with MD5-hashed filenames

图片以MD5哈希命名存储

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:
```yaml
imageCaption: "Description | Wikimedia Commons | CC BY-SA 4.0"
curl -o public/images/wiki/$(echo "filename.jpg" | md5sum | cut -d' ' -f1).jpg
"https://commons.wikimedia.org/wiki/Special:FilePath/Taiwan_landscape.jpg"

前置元数据中的图片署名格式：
```yaml
imageCaption: "描述 | 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.
文章会自动出现在
/graph
路径下的D3.js知识图谱中。节点由文章生成；边由共享标签和交叉引用生成。

Linking Articles

关联文章

Reference other articles within content using relative paths:
markdown
台灣的[半導體產業](/technology/tsmc)是台積電...

See also: [Bubble Tea](/food/bubble-tea) for more on Taiwan's soft power.
在内容中使用相对路径引用其他文章：
markdown
台灣的[半導體產業](/technology/tsmc)是台積電...

另见：[珍珠奶茶](/food/bubble-tea)了解更多台湾软实力相关内容。

Tagging for Graph Connections

通过标签建立图谱连接

Use consistent tags to create knowledge graph bridges:
markdown
undefined
使用一致的标签来构建知识图谱关联：
markdown
undefined

Both articles tagged [democratic transition] will be connected

两篇都带有[democratic transition]标签的文章会建立连接

tags: [democratic transition, civil society, 1990s]

---
tags: [democratic transition, civil society, 1990s]

---

Sync Workflow

同步工作流

After editing any file in 
knowledge/
, always sync before building:
bash
undefined
在
knowledge/
目录中编辑任何文件后，构建前务必执行同步：
bash
undefined

1. Edit content

1. 编辑内容

vim knowledge/Food/new-article.md vim knowledge/en/Food/new-article.md
vim knowledge/Food/new-article.md vim knowledge/en/Food/new-article.md

2. Sync to src/content/

2. 同步到src/content/

bash scripts/sync.sh
bash scripts/sync.sh

3. Verify build

3. 验证构建

npm run build
npm run build

4. Preview

4. 预览

npm run preview

---
npm run preview

---

Three-Layer Depth Pattern

三层深度模式

Every article should follow this structure for AI-readability and varied reading levels:
markdown
undefined
每篇文章都应遵循此结构，以确保AI可读性并适配不同阅读水平：
markdown
undefined

30 秒認識 / 30-Second Overview

30 秒認識 / 30-Second Overview

[2-3 sentences, the essential fact]
[2-3句话，核心事实]

深度閱讀 / Deep Dive

深度閱讀 / Deep Dive

Subsection 1

小节1

[Detailed exploration with data]
[含数据的详细探讨]

Subsection 2

小节2

[Historical context or comparison]
[历史背景或对比分析]

為什麼重要 / Why This Matters

為什麼重要 / Why This Matters

[Curatorial perspective — answer "why should the world care?"]
[策划视角 — 解答“为何全球需要关注？”]

參考資料 / References

參考資料 / References

[Clickable URLs only — no plain-text citations]

---
[仅可点击URL — 不接受纯文本引用]

---

Contributing via PR

通过PR贡献内容

Full PR Workflow

完整PR工作流

bash
undefined
bash
undefined

1. Fork and clone

1. Fork并克隆仓库

git clone https://github.com/YOUR_USERNAME/taiwan-md.git cd taiwan-md
git clone https://github.com/YOUR_USERNAME/taiwan-md.git cd taiwan-md

2. Create branch

2. 创建分支

git checkout -b add/food/scallion-pancake
git checkout -b add/food/scallion-pancake

3. Add zh-TW article

3. 添加繁体中文文章

cat > knowledge/Food/scallion-pancake.md << 'EOF'

title: 蔥抓餅 description: ... category: food date: 2024-01-20 sources:
  • title: Source url: https://...
Content here... EOF

cat > knowledge/Food/scallion-pancake.md << 'EOF'

title: 蔥抓餅 description: ... category: food date: 2024-01-20 sources:
  • title: 来源 url: https://...
内容... EOF

4. Add English translation

4. 添加英文翻译版本

mkdir -p knowledge/en/Food cat > knowledge/en/Food/scallion-pancake.md << 'EOF'

title: Scallion Pancake ... EOF

mkdir -p knowledge/en/Food cat > knowledge/en/Food/scallion-pancake.md << 'EOF'

title: Scallion Pancake ... EOF

5. Sync and test

5. 同步并测试

bash scripts/sync.sh npm run build
bash scripts/sync.sh npm run build

6. Commit and PR

6. 提交并发起PR

git add knowledge/ git commit -m "feat(food): add scallion pancake article (zh+en)" git push origin add/food/scallion-pancake
undefined
git add knowledge/ git commit -m "feat(food): add scallion pancake article (zh+en)" git push origin add/food/scallion-pancake
undefined

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]
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

AI原生特性

llms.txt

llms.txt

The site exposes 
/llms.txt
for AI consumption. When writing content, use structured headers that AI can parse:
markdown
undefined
站点提供
/llms.txt
供AI读取。撰写内容时，请使用AI可解析的结构化标题：
markdown
undefined

Title

标题

Key fact: One-sentence essential truth.
关键事实： 一句话核心真相。

Context

背景

...
...

Significance

重要性

...
undefined
...
undefined

Meta AI Summary Tag

Meta AI摘要标签

Pages include 
<meta ai-summary>
— write descriptions that work as standalone AI context:
yaml
description: "台積電（TSMC）生產全球90%最先進晶片，是台灣的「矽盾」——台灣的地緣政治生存策略。"
页面包含
<meta ai-summary>
— 请撰写可作为独立AI上下文的描述：
yaml
description: "台積電（TSMC）生產全球90%最先進晶片，是台灣的「矽盾」——台灣的地緣政治生存策略。"

Astro Page Patterns

Astro页面模式

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

分类页面（
src/pages/[category].astro
）

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>
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
/food/bubble-tea        ← 繁体中文（默认）
/en/food/bubble-tea     ← 英文

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
提交PR前，请验证：
  • 同时存在
    knowledge/[Category]/article.md
    （繁体中文）和
    knowledge/en/[Category]/article.md
    （英文）
  • 所有
    sources
    条目都包含可点击的
    url
    字段（不接受仅纯文本的参考）
  • 文章遵循三层深度结构：30秒概述 → 深度阅读 → 重要性分析
  • 图片来自Wikimedia Commons且带有正确的
    imageCaption
    署名
  • category
    标识与12个有效分类之一完全匹配
  • bash scripts/sync.sh && npm run build
    执行无错误
  • 事实性声明已通过引用来源验证

Troubleshooting

故障排除

Build fails after adding article

添加文章后构建失败

bash
undefined
bash
undefined

Check frontmatter syntax

检查前置元数据语法

cat knowledge/Food/my-article.md | head -20
cat knowledge/Food/my-article.md | head -20

Common issue: missing required fields

常见问题：缺少必填字段

Ensure title, description, category, date are all present

确保title、description、category、date均已填写

Re-sync and rebuild

重新同步并构建

bash scripts/sync.sh npm run build 2>&1 | grep ERROR
undefined
bash scripts/sync.sh npm run build 2>&1 | grep ERROR
undefined

Article not appearing in knowledge graph

文章未出现在知识图谱中

bash
undefined
bash
undefined

Ensure tags array is populated

确保标签数组已填充

Check category slug matches exactly (case-sensitive)

检查分类标识是否完全匹配（区分大小写）

Verify sync was run after editing

验证编辑后已执行同步

bash scripts/sync.sh
undefined
bash scripts/sync.sh
undefined

English article not showing at /en/...

英文文章未在/en/...路径显示

bash
undefined
bash
undefined

Verify file exists at correct path

验证文件是否存在于正确路径

ls knowledge/en/Food/my-article.md
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
undefined
grep "category:" knowledge/Food/my-article.md grep "category:" knowledge/en/Food/my-article.md
undefined

Images not loading

图片无法加载

bash
undefined
bash
undefined

Images must be cached locally in public/images/wiki/

图片必须在本地缓存于public/images/wiki/目录

ls public/images/wiki/
ls public/images/wiki/

Verify frontmatter path starts with /images/wiki/

验证前置元数据中的路径以/images/wiki/开头

grep "image:" knowledge/Food/my-article.md
grep "image:" knowledge/Food/my-article.md

Should be: image: /images/wiki/filename-hash.jpg

正确格式应为：image: /images/wiki/filename-hash.jpg

undefined
undefined

Sync script permission error

同步脚本权限错误

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

Resources

资源