下面示範 「把你現有的 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!祝部署順利