Taco 使用手册
Taco 使用手册
欢迎使用 Taco！这是一个基于 Next.js 构建的现代化博客系统。本手册将详细介绍所有功能和使用方法。
🚀 快速开始
环境要求
- Node.js 18.0.0 或更高版本
- pnpm 8.0.0 或更高版本
安装和启动
# 1. 克隆项目
git clone <repository-url>
cd taco-blog
# 2. 安装依赖
pnpm install
# 3. 启动开发服务器
pnpm dev
# 4. 打开浏览器访问
http://localhost:3000
项目结构
Taco/
├── data/ # 数据文件
│ ├── posts/ # 文章目录
│ │ ├── essays/ # 技术文章
│ │ ├── pieces/ # 随笔文章
│ │ └── yearly/ # 年度总结
│ ├── pages/ # 静态页面
│ ├── categories.data.js # 分类配置
│ ├── home.data.js # 首页配置
│ ├── links.data.js # 友情链接
│ ├── media.data.js # 媒体库数据
│ └── projects.data.js # 项目展示
├── src/
│ ├── app/ # Next.js App Router
│ ├── components/ # 组件库
│ ├── lib/ # 工具函数
│ └── styles/ # 样式文件
└── public/ # 静态资源
📝 内容管理
1. 发布文章
创建新文章
在 data/posts/ 的相应分类目录下创建 .md 文件：
---
title: '文章标题'
date: '2024-01-15'
category: 'essays'
banner:
img: "https://example.com/banner.jpg"
title: "横幅标题"
subtitle: "横幅副标题"
---
# 文章内容
这里是文章的正文内容...
Front Matter 字段说明
| 字段 | 类型 | 必需 | 说明 |
|---|---|---|---|
title |
string | ✅ | 文章标题 |
date |
string | ✅ | 发布日期 (YYYY-MM-DD) |
category |
string | ✅ | 分类 slug |
banner.img |
string | ❌ | 横幅背景图 |
banner.title |
string | ❌ | 横幅标题 |
banner.subtitle |
string | ❌ | 横幅副标题 |
支持的 Markdown 语法
# 一级标题
## 二级标题
### 三级标题
**粗体** 和 *斜体*
`行内代码`
\`\`\`javascript
// 代码块
function hello() {
console.log('Hello, World!')
}
\`\`\`
- 无序列表
1. 有序列表
[链接文本](https://example.com)
| 表格 | 标题 |
|------|------|
| 内容 | 内容 |
> 引用块
2. 管理分类
编辑分类配置
在 data/categories.data.js 中管理分类：
const categories = {
"essays": {
slug: "essays",
name: "技术文章",
description: "技术相关的深度文章",
banner: "https://example.com/banner.jpg",
title: "技术文章",
subtitle: "代码与思考"
}
}
添加新分类
- 在
data/posts/下创建新目录 - 在
categories.data.js中添加配置 - 创建测试文章验证功能
3. 配置友情链接
编辑 data/links.data.js：
const linksData = {
title: "友情链接",
content: "这里是友情链接说明",
banner: {
title: "友情链接",
subtitle: "Friends Links",
img: "https://example.com/banner.jpg"
},
list: [
{
name: "链接名称",
link: "https://example.com",
img: "https://example.com/avatar.jpg",
description: "链接描述"
}
]
}
4. 项目展示管理
编辑 data/projects.data.js：
const projectsData = {
title: "项目展示",
banner: {
title: "项目展示",
subtitle: "Project Showcase",
img: "https://example.com/banner.jpg"
},
projects: [
{
name: "项目名称",
description: "项目描述",
image: "https://example.com/project.jpg",
link: "https://project-demo.com",
github: "https://github.com/user/project",
tags: ["React", "Next.js", "TailwindCSS"]
}
]
}
📚 媒体库功能
添加书籍记录
在 data/media.data.js 的 books 数组中添加：
{
id: 1,
title: "书籍标题",
author: "作者",
cover: "https://example.com/book-cover.jpg",
rating: 5,
category: "技术",
readDate: "2024-01-15",
review: "读后感想..."
}
添加影视记录
在 data/media.data.js 的 movies 数组中添加：
{
id: 1,
title: "电影标题",
director: "导演",
cover: "https://example.com/movie-poster.jpg",
rating: 4.5,
category: "剧情",
watchDate: "2024-01-15",
review: "观后感想..."
}
媒体库字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
id |
number | 唯一标识符 |
title |
string | 标题 |
author/director |
string | 作者/导演 |
cover |
string | 封面图片链接 |
rating |
number | 评分 (1-5) |
category |
string | 分类 |
readDate/watchDate |
string | 阅读/观看日期 |
review |
string | 评价或感想 |
🎨 样式自定义
1. 修改主题色彩
编辑 tailwind.config.js：
theme: {
extend: {
colors: {
primary: {
50: '#eff6ff',
500: '#3b82f6',
900: '#1e3a8a'
}
}
}
}
2. 自定义全局样式
编辑 src/styles/globals.sass：
body
background-color: var(--bg-primary)
font-family: var(--font-sans)
.custom-class
@apply bg-blue-500 text-white
border-radius: 8px
3. 暗色主题配置
编辑 src/styles/_dark.sass：
[data-theme="dark"]
--bg-primary: #0f172a
--text-primary: #f8fafc
--border: #334155
4. 代码高亮主题
编辑 src/styles/lib/prism.css 来自定义代码高亮样式。
🔧 功能配置
1. 网站基本信息
编辑 data/home.data.js：
const config = {
banner: {
title: "网站标题",
subtitle: "副标题",
img: "横幅图片链接"
},
about: {
names: "作者名称",
des: "用户描述",
character: "个性标签"
},
nav: {
list: [
{
link: "/media",
title: "媒体库",
des: "记录读过的书和看过的电影",
target: "_self"
}
]
}
}
2. SEO 配置
编辑 src/app/layout.js 中的 metadata：
export const metadata = {
title: {
default: '网站标题',
template: '%s | 网站标题'
},
description: '网站描述',
openGraph: {
type: 'website',
locale: 'zh_CN',
},
}
3. 评论系统
博客集成了 Giscus 评论系统，在 src/app/blog/[slug]/components/Comment.js 中配置：
<Giscus
repo="your-username/your-repo"
repoId="your-repo-id"
category="Announcements"
categoryId="your-category-id"
mapping="pathname"
theme="preferred_color_scheme"
/>
📱 响应式设计
博客系统已经实现了完整的响应式设计：
断点系统
xs: 475pxsm: 640pxmd: 768pxlg: 1024pxxl: 1280px2xl: 1536px
移动端优化
- 触摸友好的界面
- 优化的字体大小
- 适配的图片尺寸
- 简化的导航菜单
🚀 部署指南
Vercel 部署
- 推送代码到 GitHub
- 在 Vercel 中导入项目
- 配置环境变量
- 自动部署完成
环境变量配置
# .env.local
NEXT_PUBLIC_SITE_URL=https://yourdomain.com
NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX
构建命令
# 本地构建测试
pnpm build
# 启动生产服务器
pnpm start
🔍 SEO 优化
自动生成的功能
- ✅ Sitemap.xml
- ✅ RSS 订阅
- ✅ Open Graph 标签
- ✅ Twitter Card
- ✅ 结构化数据
最佳实践
- 为每篇文章设置独特的标题和描述
- 使用高质量的横幅图片
- 合理设置文章分类
- 定期更新内容
⚡ 性能优化
自动优化功能
- 图片自动优化和懒加载
- 代码分割和预加载
- CSS 和 JavaScript 压缩
- 静态资源缓存
监控工具
- Lighthouse 性能评分
- Core Web Vitals 监控
- 错误日志收集
🛠 开发指南
开发环境设置
# 安装依赖
pnpm install
# 启动开发服务器
pnpm dev
# 代码检查
pnpm lint
# 类型检查
pnpm type-check
代码规范
- ESLint 代码检查
- Prettier 代码格式化
- TypeScript 类型检查
- 统一的 Git 提交规范
自定义组件开发
在 src/components/ 目录下创建新组件：
// src/components/CustomComponent.js
export default function CustomComponent({ children }) {
return (
<div className="custom-component">
{children}
</div>
)
}
🤝 贡献指南
报告问题
在 GitHub Issues 中提交 bug 报告或功能请求。
提交代码
- Fork 项目
- 创建功能分支
- 提交代码
- 创建 Pull Request
开发规范
- 遵循现有的代码风格
- 添加必要的测试
- 更新相关文档
- 确保所有检查通过
❓ 常见问题
Q: 如何修改网站标题？
A: 编辑 src/app/layout.js 中的 metadata 配置。
Q: 如何添加新的页面？
A: 在 src/app/ 目录下创建新的路由文件夹。
Q: 如何自定义 404 页面？
A: 编辑 src/app/not-found.js 文件。
Q: 如何开启 Google Analytics？
A: 在环境变量中设置 NEXT_PUBLIC_GA_ID。
📞 技术支持
如果在使用过程中遇到问题：
- 查看本使用手册
- 搜索 GitHub Issues
- 提交新的 Issue
- 参考 Next.js 官方文档
🎉 总结
Taco 提供了完整的博客功能：
- ✅ 文章管理和发布
- ✅ 分类系统
- ✅ 媒体库记录
- ✅ 项目展示
- ✅ 响应式设计
- ✅ SEO 优化
- ✅ 性能优化
- ✅ 主题自定义
开始使用 Taco 创建你的博客吧！🚀
版本: 1.0.0
最后更新: 2024年12月31日