Docusaurus v3.9 + TailwindCSS 範例

December 12, 2025 · 4 min read

Smile Hsu

Full-stack developer ,Data Analyst

前言:

這是一個完整的 Docusaurus 3.9 搭配 TailwindCSS 4 的設定範例，
並且支援 GitHub Pages 自動部署。

🖼 成果圖: demo

📦 安裝流程

1️⃣ 建立新專案

npx create-docusaurus@latest mywebsite classic
cd mywebsite

2️⃣ 安裝必要套件

npm install tailwindcss @tailwindcss/postcss autoprefixer

3️⃣ 建立 Tailwind 設定檔

手動建立檔案：src/plugins/tailwind.config.js

module.exports = function tailwindPlugin(context, options) {
    return {
        name: "tailwind-plugin",
        configurePostCss(postcssOptions) {
            postcssOptions.plugins.push(require("@tailwindcss/postcss"));
            return postcssOptions;
        },
    };
};

4️⃣ 修改 src/css/custom.css

/* 最前面加 */
@import "tailwindcss/theme.css" layer(theme);

@layer base {
    #tw-scope {
        @import "tailwindcss/preflight.css" layer(base);
    }
}

@import "tailwindcss/utilities.css" layer(utilities);

@custom-variant dark (&:is([data-theme="dark"] *));

5️⃣ 修改 Docusaurus 設定

📝 編輯 `docusaurus.config.js`

const config = {
    title: "My Site",
    tagline: "Dinosaurs are cool",
    favicon: "img/favicon.ico",

    //新增的部分
    plugins: ["./src/plugins/tailwind-config.js"],

    // 把 footer:{} 整段註解掉

}

🧩 範例首頁 (要用就複製貼上)

src/pages/index.js

import React from "react";
import Layout from "@theme/Layout";
import Link from "@docusaurus/Link";

export default function Home() {
    return (
        <Layout>
            {/* 整體背景與 Hero 區 */}
            <div className="tailwind bg-gradient-to-br from-blue-500 to-purple-600 text-white min-h-screen flex flex-col">
                <header className="text-center mt-20">
                    <h1 className="text-5xl font-bold mb-4 tracking-tight text-green-500">
                        Welcome to My Docusaurus Site
                    </h1>
                    <p className="text-lg text-blue-100 max-w-2xl mx-auto">
                        使用 Tailwind CSS
                        打造的現代化首頁設計，簡潔、美觀且快速。
                    </p>
                    <div className="mt-8">
                        <Link
                            to="/docs/intro"
                            className="px-8 py-3 bg-white text-purple-700 font-semibold rounded-lg shadow hover:bg-gray-200 transition"
                        >
                            開始探索
                        </Link>
                    </div>
                </header>

                {/* 卡片區塊 */}
                <section className="mt-24 px-6 grid grid-cols-1 md:grid-cols-3 gap-8 max-w-6xl mx-auto">
                    {[
                        {
                            title: "文件系統",
                            desc: "探索 Docusaurus 的強大文件功能與模組化設計。",
                            icon: "📘",
                            color: "from-indigo-600 to-indigo-800",
                        },
                        {
                            title: "部落格文章",
                            desc: "撰寫技術筆記與分享，內建 RSS 與 SEO 最佳化。",
                            icon: "✍️",
                            color: "from-purple-600 to-purple-800",
                        },
                        {
                            title: "自訂樣式",
                            desc: "結合 Tailwind CSS，創造專屬於你的風格體驗。",
                            icon: "🎨",
                            color: "from-blue-600 to-blue-800",
                        },
                    ].map((card, index) => (
                        <div
                            key={index}
                            className={`bg-gradient-to-br ${card.color} p-8 rounded-2xl shadow-lg hover:scale-105 transform transition duration-300`}
                        >
                            <div className="text-5xl mb-4">{card.icon}</div>
                            <h3 className="text-2xl font-semibold mb-3">
                                {card.title}
                            </h3>
                            <p className="text-gray-100">{card.desc}</p>
                        </div>
                    ))}
                </section>

                {/* CTA 區塊 */}
                <section className="mt-24 mb-16 text-center">
                    <h2 className="text-3xl font-bold mb-4">
                        🚀 開始打造屬於你的技術部落格
                    </h2>
                    <p className="text-blue-100 mb-6">
                        使用 Docusaurus + Tailwind 快速建立美觀、可擴充的網站。
                    </p>
                    <Link
                        to="/blog"
                        className="px-8 py-3 bg-purple-800 hover:bg-purple-700 rounded-lg shadow font-semibold transition"
                    >
                        前往部落格
                    </Link>
                </section>

                {/* Footer */}
                <footer className="mt-auto py-6 text-center border-t border-white/10 text-sm text-blue-200">
                    © {new Date().getFullYear()} My Docusaurus Site. All rights
                    reserved. Made with ❤️ ChatGPT and Tailwind CSS.
                </footer>
            </div>
        </Layout>
    );
}

🚀 部署到 GitHub Pages

1️⃣ 修改設定

在 docusaurus.config.js 加入：

url: "https://你的帳號.github.io",
baseUrl: "/你的-repo-name/",
projectName: "你的-repo-name",
organizationName: "你的帳號",
deploymentBranch: "gh-pages",
trailingSlash: false,

// 😎 我的設定 
// Set the production url of your site here
// 新增修改的部分
url: "https://rs6000.github.io", // 你的 GitHub Pages 網址
baseUrl: "/myblog/", // repo 名稱，前後都要加斜線

organizationName: "rs6000", // GitHub 帳號
projectName: "myblog", // repo 名稱
deploymentBranch: "gh-pages",
trailingSlash: false, // 建議加上

onBrokenLinks: "throw",

2️⃣ 執行部署

npm run build
npm run deploy

🤖 GitHub Actions 自動部署（可選）

建立 .github/workflows/deploy.yml

name: Deploy Docusaurus to GitHub Pages
on:
  push:
    branches: [ main ]
jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - run: npx docusaurus deploy --yes

✅ 驗證 Tailwind 是否生效

在首頁加上：

<h2 className="text-3xl text-green-500">TailwindCSS 已啟用！</h2>

如果出現綠色字樣，代表設定成功 🎉

🧰 常見問題

如果 npx tailwindcss init 無法執行 → Tailwind v4 不再使用 init 指令。
若樣式衝突，可用限定範圍 .tailwind 容器包覆首頁內容。

前言:​

📦 安裝流程​

1️⃣ 建立新專案​

2️⃣ 安裝必要套件​

3️⃣ 建立 Tailwind 設定檔​

4️⃣ 修改 src/css/custom.css​

5️⃣ 修改 Docusaurus 設定​

📝 編輯 docusaurus.config.js​

🧩 範例首頁 (要用就複製貼上)​

🚀 部署到 GitHub Pages​

1️⃣ 修改設定​

2️⃣ 執行部署​

🤖 GitHub Actions 自動部署（可選）​

✅ 驗證 Tailwind 是否生效​

🧰 常見問題​

🧡 製作資訊​

前言: