> ## Documentation Index
> Fetch the complete documentation index at: https://felimet-hub.jmcores.com/llms.txt
> Use this file to discover all available pages before exploring further.
# AGENT
# Felimet Hub — 網站維護憲章（給 AI 維護者）
這個 repo 是 **Felimet Hub 個人網站**（線上 [www.jmcores.com）的原始碼，平台是](http://www.jmcores.com）的原始碼，平台是) **Mintlify**（docs.json 驅動的文件站），雙語（繁體中文 zh-Hant 為主、English 為輔）。設計基調 wabi-sabi 暖色。
維護者預設用**自然語言**下指令（例：「幫我加一篇關於 vLLM 部署的筆記」「把 Schlieren 那篇標成精選」「準備發布」）。本檔 + `.claude/skills/` 是把那些自然語言對應到正確、可重現操作的單一事實來源。**動手前先讀本檔對應段落，不要憑印象改。**
***
## 1. 環境與指令（本地驗證不需帳號）
| 動作 | 指令 | 說明 |
| ------- | ------------------------------------ | ------------------------------------ |
| 安裝/驗證設定 | `npx -y mint@latest validate` | strict build 驗證，exit 0 才算過。CI 與發布前必跑 |
| 本地預覽 | `npx -y mint@latest dev --port 3001` | port 3000 常被占，固定用 3001。背景跑 |
| 壞連結掃描 | `npx -y mint@latest broken-links` | 發布前選用 |
| 重產畫廊資料 | `node scripts/gen-gallery.mjs` | 改任何畫廊文章 frontmatter 後必跑 |
需求：Node >= 20.17（實測 v24 OK）。`mint dev` 起來後 curl 輪詢 `http://localhost:3001/` 回 200 再截圖。收工用 PowerShell `Get-NetTCPConnection -LocalPort 3001 -State Listen` 找 PID kill。
**HMR 規則（重要）**：
* `.mdx` / `.css` / `.svg` 改動 → dev 熱更新會生效。
* `docs.json` / `snippets/*.jsx` 改動 → **必須重啟 dev**，HMR 不重載，會 serve 舊 chunk 騙人。
***
## 2. 目錄結構與檔案落點
```
jmcores-docs/
├── docs.json # 唯一導覽/主題設定來源：tabs、languages、色票、字型、logo、footer
├── style.css # wabi-sabi 自訂層（Mintlify 自動載入，接在框架樣式後）
├── footer-copyright.js # 注入 footer 可點 copyright 行（含 /privacy 連結）；Mintlify 自動載入根目錄 .js
├── index.mdx # 首頁（mode: custom，乾淨 landing）
├── about.mdx / about/journey.mdx
├── privacy.mdx
├── projects/ notes/ publications/ # 繁中內容（root = zh-Hant，無語言前綴）
│ └── */overview.mdx # 各區畫廊頁（import Gallery + 對應資料）
├── en/ # 英文鏡像（與 root 同結構，路徑前綴 /en）
├── snippets/
│ ├── gallery.jsx # 畫廊 React 元件（篩選 chip + 排序，useState）
│ ├── gallery-data.jsx # 自動產生，勿手改（gen-gallery.mjs 輸出）
│ ├── arch-flow.jsx # 互動式架構/資料流檢視器（ArchFlow，專案頁 ## 專案架構 用，useState + 自帶明暗主題）
│ ├── option-picker.jsx # 可重用方案/版本選擇器（OptionPicker，多方案專案：Bitwarden/RustDesk/SAM2…）
│ ├── stale-validator.jsx# 溫濕度頁專用：四訊號失聯驗證互動演示（StaleValidator）
│ ├── upload-demo.jsx # Cloudflare R2 頁專用：上傳動畫 mock（UploadDemo，useState + useEffect）
│ ├── lameness-grades.jsx# 乳牛跛行頁專用：四等級 + GEI/HEI 融合權重滑桿（LamenessGrades）
│ ├── cert-decision.jsx # Synology 頁專用：流量路徑 → 推薦憑證決策（CertDecision）
│ ├── terminal-demo.jsx # 可重用模擬終端機：逐行打字 + mock 輸出 + play/step/reset（TerminalDemo，cuda-setup 用）
│ ├── cite-switch.jsx # 論文引用格式切換（CiteSwitch，解析 BibTeX → IEEE/APA + 複製，publications 用）
│ └── pub-meta.jsx # 論文中繼資料 pills 元件
├── images/ # 所有圖：mark/wordmark logo、lobe/ AI 品牌 icon、skill-icons/ 技能 icon、各文章圖（含子資料夾如 cuda-setup/）
├── scripts/
│ ├── gen-gallery.mjs # 掃本 repo frontmatter → gallery-data.jsx（雙語）
│ ├── og-cover.html # 首頁 OG 設計卡產生器（1200x630），Playwright 截圖 → images/og-cover.png
│ ├── og-background.html # 逐頁 OG 無文字品牌底圖產生器 → images/og-background.png
│ ├── og-logo.svg # OG 產生器共用 JM 標記（兩個 HTML 以 ![]()
引用）
│ └── *.mjs # 一次性遷移工具（convert/fix-*），日常維護用不到
└── .github/workflows/update-gallery.yml # push 改內容自動重產 gallery-data
```
圖片落點：文章圖放 `images/`，多圖的文章開子資料夾（如 `images/cuda-setup/fig1.png`），MDX 以絕對路徑引用 `/images/cuda-setup/fig1.png`。
***
## 3. Frontmatter Schema（畫廊靠這些欄位）
每篇納入畫廊的文章（projects / notes / publications，overview 除外）frontmatter 至少：
```yaml theme={null}
---
title: "標題"
description: "一句話描述（畫廊卡片摘要，> 88 字會截斷）"
tags: ["標籤A", "標籤B"] # 畫廊篩選用
featured: true # 選填，精選排前
order: 1 # 選填，featured 內排序（小在前，預設 999）
date: "2025-06" # publications 排序用（新→舊）
# --- 僅 publications ---
pubType: "journal" # journal / conference
venue: "IEEE Trans. ..." # 期刊/會議名（畫廊卡片顯示）
confType: "" # 選填
award: "" # 選填
draft: true # 設了就不上站、不進畫廊（gen-gallery 跳過）
---
```
Mintlify 忽略它不認得的 key，所以這些自訂欄位安全。**新文章一定要帶 tags（否則畫廊篩選缺項）。**
***
## 4. 雙語原子規則（i18n 不能半開）
`docs.json` 的 `navigation.languages` 一旦啟用，**每個語言的內容必須齊全**，否則切到該語言會空白破頁。
鐵則：**任何納入導覽的頁面，root（繁中）與 `en/`（英文）必須同時存在、同時登記進 docs.json 的兩個語言區塊。** 新增一頁 = 建兩個檔 + 改 docs.json 兩處。只做單語 = 破站。
* root 路徑：`notes/foo/bar.mdx` → 網址 `/notes/foo/bar`
* en 路徑：`en/notes/foo/bar.mdx` → 網址 `/en/notes/foo/bar`
* 英文頁的內部連結要加 `/en` 前綴。
***
## 5. 畫廊維護
* 資料來源：`scripts/gen-gallery.mjs` 掃**本 repo** root + `en/` 的 frontmatter，輸出 `snippets/gallery-data.jsx`（exports `projects/notes/publications` + `projectsEn/notesEn/publicationsEn`）。
* 改了任何畫廊文章的 title/description/tags/featured/order/draft → **跑 `node scripts/gen-gallery.mjs`**，否則畫廊不同步。
* GitHub Action（`.github/workflows/update-gallery.yml`）會在 push 改內容時自動重產，但本地驗證前自己先跑一次比較準。
* `gallery-data.jsx` 標頭寫「自動產生勿手改」，要改畫廊內容去改來源 MDX frontmatter，不是改這個檔。
***
## 6. 設計系統（沿用，不要亂動）
* 色票（docs.json colors）：primary `#bf7551`（sienna 主互動色）、light `#cf8a68`、dark `#a85f3f`。背景 cream `#F9F7F2` / slate `#1F1F21`。
* 字型（docs.json `fonts`）：heading Crimson Pro、body Noto Sans TC。**兩者皆 Google Fonts，採 family-only 寫法 = Mintlify 自動走 Google Fonts API 載入**（官方：指定 Google Font family 名即自動載入，無需 source URL）。**不要為它們加 `source`**，那會切成自架 woff2、脫離 Google Fonts API。要換字型才動 family，否則別碰。
* 西文散文字形 Noto Serif（2026-06-12 使用者指定）：docs.json fonts 只有兩槽，第三 family 由根目錄 `fonts-noto-serif.js` 注入 Google Fonts 載入，`style.css` 散文堆疊把 `"Noto Serif"` 插在 `"Noto Sans TC"` 前（拉丁碼位走 serif，CJK 自然回退）。標題仍 Crimson Pro、code 仍等寬，皆不受影響。
* 圖示（docs.json `icons.library: "lucide"`）：全站 `icon=` 走 [Lucide](https://lucide.dev)，**所有 icon 名稱必須是 Lucide 名**（非 FontAwesome）。新增頁面用 Lucide 名（如 `triangle-alert` 非 `warning`、`mail` 非 `envelope`、`file-text` 非 `document`）。Lucide 核心已移除 brand icon（github/linkedin 等）：brand 用 `icon={}` 內嵌 SVG（about 頁的 GitHub/LinkedIn/ORCID 即此法），保留品牌外形又隨主題色。
* 社群分享（docs.json `seo` + `thumbnails`）：逐頁 OG（Mintlify 自動產，品牌底圖 `images/og-background.png` + `thumbnails.theme`），首頁用完整設計卡 `images/og-cover.png`。細節見 §8.4 與 `.claude/rules/og-cards.md`。
* logo：一體式 wordmark SVG（`images/logo-wordmark.svg` 亮 / `logo-wordmark-dark.svg` 暗，含 JM mark + Georgia「Felimet Hub」字）。docs.json logo 指這兩個。`mark.svg`（純 JM）目前未用於 nav，留作他用。
* 自訂色一律走 `style.css` 的具名 class（如畫廊 `.g-*`），**不要用 `var(--sl-*)`**（那是 Starlight 變數，Mintlify 沒有，會 fallback 出錯）。暗色模式靠 `html.dark`。
* 散文排版：段落級散文（含 Mintlify 的 `span[data-as="p"]`、p、li、blockquote、dd）**兩端對齊**（justify + 英文 hyphens 斷字），標題／表格欄／圖說／code 維持 start（實作在 `style.css`「散文兩端對齊」段，2026-06-11 定案）。渲染層引號規則（直引號 JS、QuoteLatin 備援）見 §8 踩雷 11 與 §8.1；細節住 `.claude/rules/house-style.md`。
***
## 7. 部署（這步要本人，AI 做不了；步驟已查證 Mintlify 官方文件）
新站走 Mintlify 託管（app.mintlify.com），**不是** Cloudflare Pages（舊 Astro 站才是）。**自訂網域 = `felimet-hub.jmcores.com`**（子網域，非 www）。流程：
1. jmcores-docs 推上 GitHub repo（已建：`github.com/felimet/felimet-hub`，private）。
2. app.mintlify.com → 裝 Mintlify GitHub App 連 repo（Settings → GitHub App → Install）。之後 push 自動 build+deploy。
3. dashboard 加自訂網域 `felimet-hub.jmcores.com` → 它給兩筆 TXT（`_acme-challenge.felimet-hub`、`_cf-custom-hostname.felimet-hub`）先加進 Cloudflare DNS，等兩筆綠勾驗證過再動 CNAME。
4. CNAME：`felimet-hub → cname.mintlify.builders`。**Cloudflare 這筆設 DNS-only（關 proxy/灰雲）** — 官方明講開 proxy 會擋憑證簽發。
5. （子網域不影響舊站）舊 www/根網域的 Cloudflare Pages 記錄可保留；felimet-hub 是新獨立子網域。
6. 等 DNS 傳播（1-24h），docs.json 設 `canonical` 指向 felimet-hub.jmcores.com。
Cloudflare 仍當 DNS provider（DNS-only）。要保留 CF proxy/WAF 在前需 Worker 進階做法（官方 /deploy/cloudflare），個人站非必要。
參考：mintlify.com/docs/customize/custom-domain、/deploy/cloudflare、/deploy/github。
## 7.1 版本控制與部署流程（每次修改都版控）
* repo：`github.com/felimet/felimet-hub`（private）。預設分支 `main`。
* **每次修改後 commit（預設只 commit，不 push）**：Conventional Commits（`feat:`/`fix:`/`docs:`/`chore:`/`refactor:`），單一職責，body 說 why。改畫廊文章 frontmatter → 先 `node scripts/gen-gallery.mjs` 再 commit。
* **push 只在使用者明說「push」時才做**（使用者偏好，2026-06-08 起）。因為 push = 觸發 Mintlify 自動部署上線，使用者要自行掌控何時上線。平時累積 commit，等他說 push 再一次推。
* push 到 `main` 後才會 → (a) `.github/workflows/validate.yml` 跑 `mint validate` CI；(b) `.github/workflows/update-gallery.yml` 自動重產 gallery-data；(c) **Mintlify GitHub App 自動 build+deploy**（這才是「自動部署」，不是 GitHub Actions — Actions 只做驗證與畫廊重產）。push 前若遠端有新 commit（CI gallery 或 PR）先 `git pull --rebase`。
* 機密永不進 git（`.gitignore` 已排除 `.env*`、`node_modules`、`.mintlify`、`.playwright-mcp`、`tmp/`）。
***
## 8. 踩雷清單（前人流血換的，照做省時間）
1. **snippet 常數放元件內**：Mintlify snippet 只認 export 的元件，module 層級的 `const` 不在 render scope → ReferenceError 整塊空白。常數寫進元件函式內。
2. **改 snippet / docs.json 要重啟 dev**：HMR 不重載這兩類，會 serve 舊版。
3. **沒有 `var(--sl-*)`**：Starlight 變數在 Mintlify 不存在，誤用會 fallback（例：暗色卡片變白底、文字隱形）。用 style.css 具名 class。
4. **原生 HTML 屬性要轉 JSX**：MDX 裡 `style="..."` 字串 / `frameborder` / `class` 會 React error #62 整頁 500。要 `style={{物件}}`、`className`、JSX 屬性。
5. **SVG logo 切邊**：先查 SVG 內部殘留的 `clipPath`（會把內容裁回舊框），不要只調 viewBox。`![]()
` 載的 SVG 吃不到 web font（Crimson Pro），文字寬不可靠 → 要嘛 textLength 釘死、要嘛轉 path、要嘛用已內嵌字體的 SVG（現用的 wordmark 內嵌 Georgia）。
6. **content 頁圖片 404**：多圖文章的圖片子資料夾要完整放進 `images/`，MDX 用絕對路徑 `/images/<夾>/<檔>`。發布前 grep 全站圖片引用對檔案存在性。
7. **Powered by Mintlify**：免費/Pro 用 CSS 隱藏違反 ToS（white-label 是 Enterprise）。現 style.css 有隱藏規則 + 警告註解；反悔刪那條即可。
8. **draft 文章**：`draft: true` 不上站、不進畫廊。目前約 13 篇草稿刻意不遷，要補才動。
9. **footer 最多 4 欄**：docs.json `footer.links` 超過 4 個 group → validate 直接擋（`maximum of 4 links columns`）。要多分類得合併。現況 4 欄＝探索 / 學術（ORCID、WoS）/ 連結（GitHub、LinkedIn、Email）/ 實驗室（ISSP & MES LAB、IMES LAB）。
10. **copyright 行可點連結 = 自訂 JS**：Mintlify footer 無自由文字欄、CSS `::after` 是生成內容不可點。copyright 行（含可點的「隱私權保護政策」→ /privacy）由 `footer-copyright.js` 注入真 DOM（`#custom-copyright`），樣式在 style.css。**Mintlify 會自動載入 repo 根目錄任何 `.js`**（等同每頁 `