Weblog 建站指南

欢迎

Weblog 是一个基于 Next.js 构建的现代博客系统，支持 MDX 内容、国际化、暗色模式、文档中心等特性。

你可以访问在线演示站点：aaronlamz.github.io/Weblog

主要特性

清新现代的设计风格
深色/浅色主题支持
中英文双语支持
响应式布局
毛玻璃导航效果
带标签和归档的博客系统
文档中心，支持分类组织、侧边栏导航

技术栈

Next.js 15 — React 全栈框架
TypeScript — 类型安全
Tailwind CSS — 样式方案
MDX — Markdown + JSX 内容格式
next-intl — 国际化支持

前置要求

开始之前，请确保你已安装以下工具：

Node.js (v18 或更高版本)
pnpm (v8 或更高版本)
Git

快速开始

克隆仓库：

bash
git clone https://github.com/aaronlamz/Weblog.git
cd Weblog

安装依赖：

bash
pnpm install

启动开发服务器：

bash
pnpm dev

现在你的站点应该运行在 http://localhost:3000 了！

配置说明

基础站点配置

主要配置文件位于 src/config/site.config.ts。以下是你需要自定义的关键部分：

typescript
export const siteConfig = {
  name: '你的站点名称',
  title: '你的站点标题',
  description: '你的站点描述',

  author: {
    name: '你的名字',
    email: 'your.email@example.com',
    avatar: 'https://github.com/你的用户名.png',
    bio: '个人简介',
  },

  social: {
    github: 'https://github.com/你的用户名',
    twitter: 'https://twitter.com/你的用户名',
    email: 'your.email@example.com',
  }
}

配置 Giscus 评论系统

Weblog 使用 Giscus 作为评论系统，它基于 GitHub Discussions。配置步骤：

确保你的仓库是公开的
在仓库中启用 GitHub Discussions：进入仓库设置 → Features → 勾选 Discussions
安装 Giscus GitHub App，选择你的仓库
访问 giscus.app，输入仓库信息，复制生成的配置
更新 src/components/comments.tsx 中的 Giscus 配置：

typescript
<Giscus
  repo="你的用户名/仓库名"
  repoId="你的仓库ID"
  category="Announcements"
  categoryId="分类ID"
  mapping="pathname"
  theme={theme === 'dark' ? 'dark_dimmed' : 'light'}
  lang={locale === 'zh' ? 'zh-CN' : 'en'}
/>

国际化配置

Weblog 默认支持中文和英文。翻译文件位于：

messages/en.json — 英文翻译
messages/zh.json — 中文翻译

在组件中使用翻译：

typescript
const t = useTranslations('namespace')
// ...
<div>{t('key')}</div>

写作博客文章

博客文章使用 MDX 格式，存储在：

content/blog/en/ — 英文文章
content/blog/zh/ — 中文文章

每篇文章都需要包含前置元数据：

mdx
---
title: "文章标题"
description: "简短描述"
date: "2024-03-20"
featured: false
tags: ["标签1", "标签2"]
---

你的文章内容...

写作文档

文档使用 MDX 格式，按分类存储在 content/docs/ 目录下：

content/docs/
└── zh/
    └── 分类目录名/
        ├── _meta.json        # 分类元数据
        ├── article-slug.mdx  # 文档文件
        └── ...

每个分类需要一个 _meta.json 文件：

json
{
  "title": "分类标题",
  "description": "分类描述",
  "icon": "BookOpen",
  "order": 1
}

文档的前置元数据：

mdx
---
title: "文档标题"
description: "文档描述"
order: 1
---

部署说明

GitHub Pages 部署

配置 GitHub Actions：工作流文件已在 .github/workflows/ 中设置好
在仓库设置中启用 GitHub Pages，将源设置为 "GitHub Actions"
推送代码即可自动部署：

bash
git add .
git commit -m "配置部署"
git push

自定义域名

在 src/config/site.config.ts 中设置 customDomain，部署时会自动生成 CNAME 文件：

typescript
customDomain: 'www.yourdomain.com',

自定义设置

样式定制

Weblog 使用 Tailwind CSS 进行样式设置。主要配置文件：

tailwind.config.ts — Tailwind 配置
src/styles/globals.css — 全局样式

组件定制

你可能想要自定义的关键组件：

src/components/header.tsx — 导航和站点头部
src/components/footer.tsx — 站点底部
src/components/theme-toggle.tsx — 暗/亮模式切换
src/components/language-switcher.tsx — 语言切换器

需要帮助？

如果遇到问题：

查看 GitHub Issues
如果找不到解决方案，创建新的 issue