寫作與部署指南

本機安裝

先安裝 Node.js 22 LTS 與 Git，用 VS Code 開啟專案資料夾。

bash

git clone https://github.com/ccatbean/engineering-wiki.git
cd engineering-wiki
npm ci
npm run docs:dev

npm ci 依 lockfile 安裝固定版本；開啟終端顯示的網址。Node 用來執行建置工具，平常仍編輯 Markdown。

bash

npm run docs:build
npm run docs:preview

建置結果在 docs/.vitepress/dist；不要提交它、cache 或 node_modules。請提交 package-lock.json，更換依賴後重新建置確認。

複製 templates/article.md 至例如 docs/linear-algebra/vector.md。
修改標題、內容與更新日期。檔名使用英文小寫與連字號。
在 docs/.vitepress/config.mts 對應分類的 items 加入 { text: '向量', link: '/linear-algebra/vector' }。
更新分類入口和 docs/questions.md，以 Markdown 連結互相引用。
圖片放在文章附近，用 ![說明](./images/example.png)；公共圖片可放 docs/public/images/ 並用 /images/example.png。
本機預覽與建置，檢查公式、連結、搜尋及手機版，再提交與 push。

bash

git add docs templates package.json package-lock.json .gitignore .nvmrc README.md
git commit -m "Add wiki article"
git push origin main

$...$ 表示行內公式，$$ 各自獨立一行表示區塊公式。貨幣美元符號用 \$，程式碼中的符號不會當成公式。

此步需要你登入 Cloudflare，並授權 ccatbean 的 GitHub repo。

在 Cloudflare Dashboard 的 Workers & Pages 建立 Pages 專案，選 Git 整合（介面名稱可能調整）。
連接 GitHub，確認擁有者為 ccatbean、repo 為 engineering-wiki，production branch 選 main。
Framework preset 選 VitePress（若沒有，選 None）。Root directory 留空。
Build command：npm ci && npm run docs:build。
Build output directory：docs/.vitepress/dist。
設定 production 與 preview 的環境變數 NODE_VERSION=22。
儲存並部署，確認建置日誌成功；打開回傳的 *.pages.dev 網址。
檢查首頁、直接開 /math-test、重新整理、搜尋、手機公式捲動。之後 push main 應自動更新 production。

這是 Cloudflare Pages 部署，不是 GitHub Pages，因此 base 保持預設 /。首次部署、GitHub 授權及自動部署需在你的帳號實際驗證。

使用 VitePress 本機搜尋（local search），索引在建置時生成，無需外部搜尋服務。中文查詢效果需用真實文章與常用關鍵字測試；可在標題及摘要加入中英文術語。Git 紀錄供還原與比較，Markdown、圖片與設定可完整搬移。