Skip to main content

Docusaurus v3.9 客製化首頁

· 4 min read
Smile Hsu
Smile Hsu
Full-stack developer ,Data Analyst

前言:​

本專案的內容是將 Blog 所有的檔案輸出成 JSON 格式，並在首頁上以卡片形式呈現。

🚀 Docusaurus v3.9 客製化首頁​

🧭 專案檔案結構​

mywebsite/                # 專案根目錄 (本機資料夾名稱)
├── .docusaurus/          # Docusaurus 編譯緩存和內部資料 (重要：Blog 資料來源)
│   └── docusaurus-plugin-content-blog/
│       └── default/
│           └── blog-post-list-prop-default.json  # <--- 腳本讀取的 Blog 原始資料
│
├── node_modules/         # 專案依賴
│
├── src/
│   ├── components/
│   │   └── LatestPosts/
│   │       └── latest-blog-posts.json    # <--- 【【自動生成】】 Blog 資料輸出目標
│   │       └── index.js                  # (可選，目前未被使用)
│   │       └── LatestPosts.module.css    # (可選，目前未被使用)
│   │
│   ├── pages/
│   │   └── index.js                      # <--- 【【首頁客製化】】 包含所有卡片和區塊樣式
│   │
│   └── plugins/
│       └── latestPostsListGenerator/     # <--- 【【新增外掛】】 Blog 資料生成邏輯
│           └── index.js                  # 外掛程式碼
│
├── static/               # 靜態資源 (如圖片、favicon)
├── blog/                 # Markdown 部落格文章
├── docs/                 # Markdown 文件
│
├── docusaurus.config.js  # <--- 【【配置修改】】 引入最新 Blog 外掛
├── package.json          # <--- 【【配置修改】】 NPM 指令與依賴
├── tailwind.config.js    # Tailwind CSS 設定檔
└── ... 其他 Docusaurus 標準檔案

📂 關鍵檔案說明​

📁 檔案/路徑🧩 作用⚙️ 狀態
src/pages/index.js包含首頁 UI、卡片樣式與 LatestBlogCards 元件。已大幅客製化
src/plugins/latestPostsListGenerator/index.js讀取 Blog 並生成 JSON 的 Docusaurus 外掛。新增
src/components/LatestPosts/latest-blog-posts.json存放最新 9 篇 Blog 文章的資料供引用。自動生成
docusaurus.config.js指向 latestPostsListGenerator 外掛路徑。已修改
package.json若採用 Node 腳本方案需修改啟動/建置指令。可選修改

🪜 步驟 0：事先準備​

要使用此專案前，請先完成前一個專案：
👉 Docusaurus v3.9 + TailwindCSS v4 範例專案

  1. 在本機建立全新的 Docusaurus 專案
  2. 完成 TailwindCSS 設定
  3. 再依照本教學進行設定
  4. 下面的程式碼，原本是完整的，但ChatGPT嫌太冗長，自動幫我刪掉了，完整程式碼都在repo裡

💡 以下步驟皆可直接複製貼上執行，本專案已實測可行

🧰 步驟 1：建立資料生成腳本​

📄 檔案位置：src/bin/latestPostsListGenerator.js

const path = require("path");
const fs = require("fs");
const moment = require("moment"); 
...
generateLatestPostList(blogPath, latestBlogPostListPath);

🧩 此腳本會讀取 .docusaurus 中的部落格資料並輸出成 JSON。

⚛️ 步驟 2：建立 React 組件​

📄 檔案：src/components/LatestPosts/index.jsx

import React from "react";
import Link from "@docusaurus/Link";
import styles from "./LatestPosts.module.css";
import latestBlogPostList from "./latest-blog-posts.json";
...

📘 樣式檔案：src/components/LatestPosts/LatestPosts.module.css

.latestPostsSection {
  padding: 60px 0;
  text-align: center;
  background-color: var(--ifm-color-emphasis-100); 
}
...

🎨 使用簡潔 CSS 呈現部落格清單區塊。

🏠 步驟 3：在首頁中加入組件​

📄 檔案：src/pages/index.jsx

import React from "react";
import Layout from "@theme/Layout";
import Link from "@docusaurus/Link";
import latestBlogPostList from "../components/LatestPosts/latest-blog-posts.json";
...
export default function Home() { ... }

💻 此檔案整合了卡片展示、CTA、Footer 與最新文章清單。
🪶 已包含 TailwindCSS 動畫與響應式設計。

⚙️ 步驟 4：更新 package.json​

📄 檔案：package.json

{
  "scripts": {
    "start": "docusaurus start",
    "build": "docusaurus build",
    "generate-blog-data": "node ./src/bin/latestPostsListGenerator.js"
  }
}

🧾 加入 "generate-blog-data" 指令，用於手動生成最新文章 JSON。

🧪 執行與使用方式​

1️⃣ 安裝依賴（若尚未安裝 moment）：

npm install moment

2️⃣ 生成 JSON 資料（首次需先跑過 npm start）：

npm run generate-blog-data
# 或
yarn generate-blog-data

3️⃣ 啟動或建構網站：

npm start
# 或
npm run build

⚠️ 部署前務必重新執行 generate-blog-data，確保最新文章資料已同步！

🌈 成果展示​

📸 首頁整合 Blog 卡片示意圖

demo1

🧾 備註​

你可以在新專案中從頭到尾複製貼上此教學內容，
保證可正常運作 ✅

🔗 Reference​

🧡 製作資訊​

📦 Made with ❤️ by ChatGPT
📜 MIT License © 2025