QuillStack
👋👋🏻👋🏼👋🏽👋🏾👋🏿
中文 | English
你好，欢迎来到 QuillStack！这是一个由 SnowBall (@SnowBall-Bqiu) 发起的 NextJS 项目。
特别说明：编译之后（out目录下）以及您编写的博文（content目录下）的所有文件的所有权归您所有，您可以将其代码可见性随意设置为私有。
🛠️ 技术栈
| 技术 | 描述 |
|---|---|
| Next.js 15 | React 框架，支持 App Router |
| Tailwind CSS | 实用优先的 CSS 框架 |
| TypeScript | 类型安全的 JavaScript |
| shadcn/ui | 精美的 UI 组件（基于 Radix UI） |
| @vercel/og | Open Graph 图片生成 |
| marked | Markdown 解析器 |
| date-fns | 日期工具库 |
✨ 功能特性
- 📱 响应式设计 - 移动端优先，适配所有设备
- 🌙 暗色/亮色主题 - 基于
next-themes的自动主题切换 - 🔍 SEO 优化 - JSON-LD、Open Graph、Twitter Cards
- 🖼️ 自动 OG 图片 - 自动生成社交分享卡片
- 🔗 友链系统 - 带申请系统的友链页面
- 📄 Markdown 支持 - 完整 Markdown 语法，支持代码高亮
- 📑 分类系统 - 按分类组织文章
- 📊 分页功能 - 可配置的每页文章数
快速开始
# 安装依赖
npm install
# 开发模式
npm run dev
# 构建生产版本
npm run build
# 启动生产服务器
npm run start
配置指南
站点配置 (content/settings.json)
站点的主配置文件，包含以下部分：
基本信息
| 字段 | 描述 | 示例 |
|---|---|---|
siteTitle |
网站标题 | "我的博客" |
siteDescription |
网站描述（用于 SEO） | "这是一个个人博客..." |
头部信息 (header)
| 字段 | 描述 | 示例 |
|---|---|---|
title |
博主姓名 | "你的名字" |
bio |
个人简介 | "我是一名软件工程师..." |
avatarUrl |
头像 URL | "https://example.com/avatar.jpg" |
heroImageUrl |
首页横幅图片 | "https://example.com/hero.jpg" |
作者信息 (author)
| 字段 | 描述 |
|---|---|
name |
作者姓名 |
avatarUrl |
作者头像 |
分页设置 (pagination)
| 字段 | 描述 | 默认值 |
|---|---|---|
postsPerPage |
每页文章数 | 10 |
导航菜单 (navigation)
"navigation": [
{ "id": "1", "label": "首页", "href": "/" },
{ "id": "2", "label": "友链", "href": "/friends" }
]
分类配置 (categories)
"categories": [
{ "id": "tech", "name": "技术", "color": "#3b82f6" },
{ "id": "server", "name": "服务器", "color": "#8b5cf6" },
{ "id": "thoughts", "name": "随笔", "color": "#f97316" }
]
| 字段 | 描述 |
|---|---|
id |
分类标识符（用于文章关联） |
name |
分类显示名称 |
color |
分类颜色（十六进制） |
底部配置 (footer)
包含底部文本、品牌信息、社交链接和链接组。
主题配置 (theme)
| 字段 | 描述 | 示例 |
|---|---|---|
bodyFont |
正文字体 | "PT Sans" |
headlineFont |
标题字体 | "Space Grotesk" |
SEO 配置 (seo)
| 字段 | 描述 |
|---|---|
siteUrl |
官方网站域名 |
keywords |
SEO 关键词数组 |
twitterHandle |
Twitter 账号 |
OG 图片配置 (ogImage)
生成社交媒体分享卡片的样式配置。
文章管理教程
文章结构
博客文章由两部分组成：
- 文章元数据：
content/sitedoc.json中的articles数组 - 文章内容：
content/doc/目录下的.md文件
添加新文章
第 1 步：创建 Markdown 文件
在 content/doc/ 目录下创建一个新的 .md 文件，例如 10.md：
## 我的第一篇文章
这里是文章内容，支持完整的 Markdown 语法。
### 小标题
- 列表项 1
- 列表项 2
**粗体**和*斜体*文本。
\`\`\`javascript
// 代码块
console.log("Hello World");
\`\`\`
如果你的代码真的~~很长，渲染后的文章代码块会自动显示一个小的水平滚动条，允许你左右滑动查看完整代码，像这样：
这是一个超级超级长的代码块\O/\O/\O/\O/\O/\O/\O/\O/\O/\O/\O/\O/\O/\O/\O/\O/\O/\O/\O/\O/\O/\O/\O/\O/\O/\O/
第 2 步：注册文章元数据
添加到 content/sitedoc.json 中的 articles 数组：
{
"id": "10",
"slug": "my-first-post",
"title": "我的第一篇文章",
"contentPath": "content/doc/10.md",
"publishedAt": "2024-08-10T12:00:00.000Z",
"excerpt": "这是文章摘要，显示在文章列表中。",
"imageUrl": "https://images.unsplash.com/photo-xxx",
"imageHint": "图片描述",
"categoryId": "tech"
}
字段说明
| 字段 | 必填 | 描述 |
|---|---|---|
id |
✅ | 文章唯一标识符（字符串） |
slug |
✅ | URL 路径标识符，例如 my-first-post |
title |
✅ | 文章标题 |
contentPath |
✅ | Markdown 文件路径 |
publishedAt |
✅ | 发布时间（ISO 8601 格式） |
excerpt |
✅ | 文章摘要（显示在列表页面） |
imageUrl |
✅ | 封面图片 URL |
imageHint |
⬜ | 图片描述（用于无障碍） |
categoryId |
✅ | 分类 ID，对应 settings.json 中的分类 |
⚠️ 注意：如果上面的可空字段导致构建错误，可以保持配置项但值为空。
文章排序
文章按 publishedAt 时间降序排列，最新的文章显示在最前面。
删除文章
- 从
sitedoc.json的articles数组中移除对应的条目 - （可选）删除对应的
.md文件
修改文章
- 直接编辑对应的
.md文件来修改内容 - 如需修改标题、摘要等，编辑
sitedoc.json中对应的条目
友链
项目包含一个友链系统，配置在 content/friends.json 中。
配置
{
"description": "友链描述",
"applyInfo": {
"title": "申请友链",
"description": "如何申请...",
"email": "your@email.com",
"agreement": "协议文本"
},
"links": [
{
"id": "friend-id",
"name": "友链名称",
"description": "友链描述",
"avatar": "https://example.com/avatar.png",
"url": "https://example.com",
"tags": ["标签1", "标签2"]
}
]
}
添加友链
- 编辑
content/friends.json - 在
links数组中添加一个新的对象 - 保存文件 - 友链页面会自动更新
OG 图片生成
项目在构建过程中会自动生成用于社交媒体分享的 Open Graph 图片。你也可以手动生成：
# 生成 OG 图片
npm run build:og
配置
OG 图片设置在 content/settings.json 的 ogImage 部分：
{
"ogImage": {
"slogan": "你的标语",
"primaryColor": "#3b82f6",
"backgroundColor": "#0f172a",
"gradientEndColor": "#1e293b",
"textColor": "#f8fafc",
"secondaryTextColor": "#94a3b8",
"tertiaryTextColor": "#64748b"
}
}
部署
Vercel（推荐）
- Fork GitHub 仓库
- 前往 Vercel 导入仓库
- Vercel 会自动检测 Next.js 并配置构建设置
- 点击部署
Netlify
- Fork GitHub 仓库
- 前往 Netlify 导入仓库
- 构建命令：
npm run build - 发布目录：
out - 点击部署
注意事项
- 修改配置后重启开发服务器
categoryId必须与settings.json中的分类id匹配- 图片建议使用 CDN 链接，避免在仓库中放置大图片
- 发布时间格式：
YYYY-MM-DDTHH:mm:ss.sssZ - 开发服务器运行在 9002 端口：
npm run dev
许可证
注意：本项目采用 AGPL-3.0 许可证。如果您使用本项目提供网络服务，必须在相同许可证下开源您的修改。
请我喝杯咖啡
| 微信 |
|---|