diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8e489b7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,84 @@
+# PhotoGrid
+
+給 Docusaurus 用的瀑布流照片牆元件。像 Instagram grid，但圖片會保持原始比例。
+
+- 電腦三欄、平板兩欄、手機一欄
+- 點擊圖片直接在新視窗開啟原圖
+- 加圖只要在陣列多寫一行路徑，不用碰元件
+
+## 預覽效果
+
+| 桌面 (3 欄) | 手機 (1 欄) |
+|---|---|
+| 瀑布流排列，圖片保持原始比例 | 單欄垂直排列 |
+
+## 安裝
+
+把 `PhotoGrid.jsx` 複製到你的 Docusaurus 專案：
+
+```
+src/
+  components/
+    PhotoGrid.jsx   ← 放這裡
+```
+
+不需要額外裝任何套件。
+
+## 使用方式
+
+### 1. 把圖片丟進 static 資料夾
+
+```
+static/
+  img/
+    gallery/
+      photo-01.jpg
+      photo-02.webp
+      photo-03.png
+```
+
+### 2. 建立一個 MDX 頁面
+
+在 `src/pages/crepe.mdx` 底下建立頁面：
+
+```mdx
+---
+title: ᓚᘏᗢ
+hide_table_of_contents: true
+---
+
+import PhotoGrid from "@site/src/components/PhotoGrid";
+
+# Gallery
+
+<PhotoGrid
+  photos={[
+    "/img/gallery/photo-01.jpg",
+    "/img/gallery/photo-02.webp",
+    "/img/gallery/photo-03.png",
+  ]}
+/>
+```
+
+未來加圖就是在 `photos` 陣列多塞一行，就這樣，沒了。
+
+## Props
+
+| 名稱 | 型別 | 預設值 | 說明 |
+|---|---|---|---|
+| `photos` | `string[]` | `[]` | 圖片路徑陣列，相對於 `/static` |
+| `columns` | `number` | `3` | 桌面版欄數 |
+| `gap` | `string` | `"12px"` | 圖片間距 |
+
+```mdx
+<!-- 想要兩欄、大間距 -->
+<PhotoGrid photos={[...]} columns={2} gap="20px" />
+```
+
+## RWD 斷點
+
+| 螢幕寬度 | 欄數 |
+|---|---|
+| > 1024px | `columns` 設定值（預設 3） |
+| 769–1024px | 2 |
+| ≤ 768px | 1 |