下面示範 「把你現有的 Markdown 資料夾 → 建立 Docusaurus 網站 → 推到 GitHub → 用 Vercel 自動部署」 的完整流程。
（假設你已經有 Node ≥ 18、Git、GitHub 及 Vercel 帳號）
0. 前置安裝
# 安裝（或確認）必要工具
node -v # ≥ 18.x
npm -v # 自帶於 Node
git --version # Git
1. 建立並克隆 GitHub 儲存庫
# GitHub 上先建立一個空 repo，例如 docs-course
git clone git@github.com:<你的帳號>/docs-course.git
cd docs-course
2. 初始化 Docusaurus 專案
建議在 repo 根目錄直接初始化，後續會把 Markdown 放到
/docs。
npx create-docusaurus@latest . classic
# 問題全部選預設即可（Site name、作者…）
npm install # 安裝依賴
執行完成後，專案結構會包含：
.
├─ docs/ ← 預設文件目錄
├─ src/
├─ docusaurus.config.js
└─ sidebars.js
3. 將你的 Markdown 搬進來
-
建立分層資料夾（建議按主題或章節）：
mkdir -p docs/course docs/units -
批次移動：
mv ../你的Markdown目錄/*.md docs/ -
若要分類，可把
course_outline.md、market_research.md… 放在docs/course/unit_1_1_article.md… 放在docs/units/unit1/之類。
tips：檔名前加
01-、02-可控制排序。
4. 自動產生側邊欄（省去手寫 sidebars.js）
打開 sidebars.js，改成：
/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
module.exports = {
docsSidebar: [{ type: 'autogenerated', dirName: '.' }],
};
只要資料夾有 README.md 或 index.md，就會被當作當層「章節首頁」。
5. 本地預覽
npm run start # http://localhost:3000
確認文件樹、連結與程式碼區塊皆正常。
6. 調整 docusaurus.config.js（最少設定）
module.exports = {
title: 'My Course Docs',
url: 'https://<YOUR-PROJECT>.vercel.app', // 部署後的正式網址
baseUrl: '/', // 若是根網域就設 /
// 其餘保持預設
};
7. Commit 並 Push
git add .
git commit -m "init docusaurus & import markdown"
git push origin main
8. 在 Vercel 啟用 Git 自動部署
-
登入 Vercel →
Add New… › Project。 -
選擇剛剛的 GitHub repo。Vercel 會自動偵測到 Docusaurus：
- Build Command：
npm run build - Output Directory：
build
- Build Command：
-
點 Deploy。第一次 Build 完成後，即會獲得
https://<YOUR-PROJECT>.vercel.app��站點。(docusaurus.io, vercel.com)
9. 之後的維運
| 操作 | 做法 |
|---|---|
編輯/新增 .md |
正常 Git commit，Vercel 會自動重新部署 |
| Pull Request 預覽 | Vercel 會自動為每個 PR 產生 Preview URL |
| 自訂網域 | Vercel 專案 → Settings → Domains 綁定 |
| Node 版本鎖定 | Settings › Build & Development Settings › Node Version（建議 18 LTS） |
| 自訂重導向 | 新增 vercel.json：json { "redirects": [{ "source": "/old", "destination": "/new", "permanent": true }]} |
10. 快速 FAQ
| 問題 | 解答 |
|---|---|
| 檔案很多要手排側邊欄很累？ | 用 autogenerated + sidebar_position 控制順序即可。 |
| 需要版本切換 (e.g. v1, v2)? | 啟用 @docusaurus/plugin-content-docs 的版本功能，或建立多 repo。 |
| 想保留 Blog | 初始化時已內含 /blog，直接寫 .md 或 MDX 即可。 |
| 公司私有文件 | Vercel Pro 以上可設定密碼保護，或在 GitHub 私有 repo 部署。 |
參考文件
- Docusaurus 官方「Deploying to Vercel」章節(docusaurus.io)
- Vercel Guide: Deploy Docusaurus(vercel.com)
- Vercel Docusaurus 2 範例模板(vercel.com)
照著以上步驟，你就能把目前這包 Markdown 快速轉成 Docusaurus 網站，並透過 GitHub + Vercel 享受 CI/CD 與全球 CDN！祝部署順利 