Astro-Theme-Aither 使用指南

本指南涵蓋從零開始到完成部署多語言部落格的完整流程。你可以從頭讀到尾，也可以直接跳到需要的章節。

前置條件

Node.js 22 LTS 或更新版本
pnpm 10 或更新版本
一個 GitHub 帳號
一個 Cloudflare 帳號（用於部署）

安裝

git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
cd YOUR_REPO
corepack enable
pnpm install
pnpm validate
pnpm dev

接著在瀏覽器中打開 http://localhost:4321。

專案結構

src/
├── components/        # Astro 與 React 元件
├── config/site.ts     # 站點名稱、導覽、頁尾、社群連結
├── content/posts/     # 依語系組織的文章內容
├── i18n/              # UI 文字翻譯
├── layouts/           # 版面元件
├── lib/               # 工具函式
├── pages/             # 路由頁面
└── styles/global.css  # Tailwind v4 主題 token

設定

站點設定

src/config/site.ts 是整個站點的單一設定來源：

1
export const siteConfig = {
2
  name: '你的部落格名稱',
3
  title: '你的標語',
4
  description: '你的站點 SEO 描述',
5
  author: {
6
    name: '你的名字',
7
    avatar: '',
8
  },
9
};

環境變數

cp .env.example .env

如果某個變數留空，對應服務就會自動停用。

站點 URL

在 astro.config.mjs 中設定正式網址：

1
import { defineConfig } from 'astro/config';
2
import aither from '@aither/astro';
3

4
export default defineConfig({
5
  site: 'https://your-domain.pages.dev',
6
  integrations: [aither()],
7
});

撰寫文章

在 src/content/posts/en/ 下建立新的 .mdx 檔案：

1
---
2
title: 我的第一篇文章
3
date: "2026-03-14T16:00:00+08:00"
4
category: General
5
description: 用於 SEO 與社群預覽的簡短摘要。
6
tags: [Topic, Another]
7
pinned: false
8
---
9

10
正文從這裡開始。

Frontmatter 參考

欄位	型別	必填	說明
`title`	string	是	文章標題
`date`	date	是	發布時間（例如 `2026-03-14T16:00:00+08:00`）
`category`	string	否	分類
`description`	string	否	SEO 描述
`tags`	string[]	否	標籤列表
`pinned`	boolean	否	是否置頂
`image`	string	否	封面圖片

MDX 元件

你可以在內容中直接匯入互動元件：

1
import MyChart from '@/components/MyChart'
2

3
<MyChart data={[10, 20, 30]} />

國際化

主題預設支援 11 種語言。要新增翻譯文章，只要在目標語系資料夾建立同名檔案：

src/content/posts/en/my-post.mdx
src/content/posts/zh-hant/my-post.mdx
src/content/posts/fr/my-post.mdx

UI 文字位於 src/i18n/messages/。

自訂內容分區

你可以透過 src/content.config.ts 與 src/config/site.ts 增加翻譯、筆記、教學等自訂集合。之後列表頁、詳情頁與導覽入口都會自動生成。

主題樣式

系統分成兩層：

顏色模式：light、dark、system
風格樣式：default 或內建樣式如 evolution

1
ui: {
2
  defaultMode: 'system',
3
  defaultStyle: 'default',
4
  showMoreThemesMenu: true,
5
},

顏色 token 位於 src/styles/global.css。預設字型為系統 sans-serif，程式碼區塊則使用 monospace。

SEO 與 AI

每個頁面都已內建以下輸出：

/sitemap-index.xml
/rss.xml
/robots.txt
/llms.txt
/llms-full.txt
/posts/slug.md
JSON-LD 與 Open Graph

部署

Cloudflare Pages

最佳實踐：先建立 Pages 專案。工作流程預設使用倉庫名稱；如果需要覆蓋，請設定 CLOUDFLARE_PAGES_PROJECT_NAME。

請在 GitHub Secrets 中設定：

CLOUDFLARE_API_TOKEN
CLOUDFLARE_ACCOUNT_ID

然後執行 pnpm validate，再推送到 main。

常用指令

指令	說明
`pnpm dev`	啟動本地開發伺服器
`pnpm validate`	執行完整的推送前驗證
`pnpm build`	建立正式環境 build
`pnpm preview`	在本機預覽 production build

版本方案

公開 release tag 使用 CalVer 風格命名，例如 v2026.04.08。