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)

![图片描述](https://example.com/image.jpg)

| 表格 | 标题 |
|------|------|
| 内容 | 内容 |

> 引用块

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: 475px
sm: 640px
md: 768px
lg: 1024px
xl: 1280px
2xl: 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日