Docusaurus 網站用 Vercel 自動部署

下面示範 「把你現有的 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 搬進來

  1. 建立分層資料夾(建議按主題或章節):

    mkdir -p docs/course docs/units
    
  2. 批次移動

    mv ../你的Markdown目錄/*.md docs/
    
  3. 若要分類,可把

    • course_outline.mdmarket_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.mdindex.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 自動部署

  1. 登入 VercelAdd New… › Project

  2. 選擇剛剛的 GitHub repo。Vercel 會自動偵測到 Docusaurus

    • Build Commandnpm run build
    • Output Directorybuild
  3. 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.jsonjson { "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 部署。

參考文件

照著以上步驟,你就能把目前這包 Markdown 快速轉成 Docusaurus 網站,並透過 GitHub + Vercel 享受 CI/CD 與全球 CDN!祝部署順利 :rocket:

以下先給出 Markdown 檔案整理建議,再附上常見開源文件 CMS/Wiki/靜態站產生器的比較表,方便你依規模與維運需求選擇。


一、最佳整理方式(面向任何支援 Markdown 的系統)

  1. 資料夾結構=導覽結構

    • 依主題或產品模組分層:/getting-started//guides//api/……
    • 每層放一個 README.md(或 index.md),作為該層目錄首頁。
  2. 檔名規則

    • 使用短斜線 slug(例:introduction.mddeploy-production.md),便於 URL 友善。
    • 如需排序可加前綴號碼:01-02-…,之後透過 CMS 的 sidebar 配置決定顯示順序。
  3. 一致的 Front-Matter(YAML/TOML)

    ---
    title: 部署到 Production
    description: 介紹如何把專案佈署到正式環境
    tags: [deploy, production]
    sidebar_position: 3
    ---
    
    • 為日後匯入不同平台(Docusaurus、MkDocs、VuePress…)提供導航、SEO 與分類資訊。
  4. 內容元件化

    • 把重複片段(例如程式區塊、警告框)抽成 include/partial 或透過 CMS 自訂元件,減少維護成本。
  5. CI 導入品質檢查

    • 在 GitHub Actions 設 lint (markdown-lint)+broken-link 檢查。
    • 若用靜態站產生器,再加自動部署到 GitHub Pages/Cloudflare Pages/Netlify。

二、常用開源文件 CMS/靜態站產生器比較

名稱 類型 特色亮點 適合情境 快速優勢 / 可能限制 GitHub ★ (2025/06) 部署方式
Docusaurus 靜態站產生器 (React) 內建版本切換、多語系、Algolia 搜尋;官方支援 MDX 元件 技術文件官網、須同站展示 Blog 前端 React 生態易擴充;需 Node 環境編譯 60.2k ★ (github.com) 靜態檔,GitHub Pages / Vercel / Netlify
MkDocs 靜態站產生器 (Python) mkdocs.yml 一檔掌管導航;Material 主題成熟 純文件、想用 Python 工具鏈 上手極快;自訂 UI 需寫 Jinja 20.5k ★ (github.com) 同上;亦可一鍵 mkdocs gh-deploy
Wiki.js Node.js Wiki 應用 即時 WYSIWYG + Markdown 雙編輯、RBAC 權限、支援多 DB 需多人協作、權限管控 UI 現代、模組豐富;佈署相對重 26.4k ★ (github.com) Docker、裸機 Node、或雲端 PaaS
BookStack PHP/Laravel Wiki 書→章→頁 分層結構直覺;內建搜尋、權限 企業內部知識庫 安裝簡單;版面較固定 16.7k ★ (github.com) LAMP/LEMP、Docker
VuePress 靜態站產生器 (Vue) Vue 元件即內容;可漸進遷移到 VitePress Vue 生態團隊、需前端互動 靈活;V1 維護模式、V2 社群維 22.8k ★ (github.com) 靜態檔;GitHub Pages/雲平台
Hugo 靜態站產生器 (Go) 極速編譯、內建 Taxonomy 與 i18n 超大量頁面、需多語系 不需 Node/Python;主題用 Go 模板 81.4k ★ (github.com) 單一二進位,任何靜態空間
Docsify 客端渲染 docs SPA 無需 Build,瀏覽器即讀 .md Demo / 簡報型文件 超輕巧;SEO 依賴 JS (需 SSR 才佳) 29.6k ★ (github.com) 放上 CDN 或 GitHub Pages 即用

如何選?

  • 只想把現有 Markdown 靜態展示 → Docsify / MkDocs 最快。
  • 文件+部落格 / 版本管理 → Docusaurus 或 Hugo。
  • 內網權限、多作者協作 → Wiki.js(高度客製)或 BookStack(介面簡潔)。
  • Vue 技術棧 → VuePress。

三、實作小提醒

  1. 先整理結構再遷移:把 Front-Matter 與檔名統一好,再選 CMS;日後要換平台才不痛。
  2. Sidebar / Menu 用配置檔治理:Docusaurus sidebars.js、MkDocs mkdocs.yml…;放 repo 根目錄就能配合 CI 驅動。
  3. 自動化搬運腳本:若原始資料散落,可寫 Node/Python 腳本批量加 Front-Matter、重命名,讓後續平台吃同一格式。
  4. 本地預覽=開發日常:選用支援 hot-reload 的系統(Docusaurus、MkDocs、VuePress)避免 commit 前看不到效果。

用以上步驟先把 內容結構定義清楚,再依維運人力與網站互動需求,選表格中的合適方案即可。祝你整理順利 :rocket: