npm package: @penjc/homepage
Description: 个人主页模板，支持博客、随笔等功能
Author: penjc
Latest version: 1.9.0

<div align="center">

# Homepage

</div>

<div align="center">
  <a href="https://pengjiancheng.com" target="_blank">
    <img src="https://github.com/penjc/homepage/blob/main/assets/homepage.svg?raw=true" width="200">
  </a>

[![npm version](https://img.shields.io/npm/v/@penjc/homepage?style=flat-square)](https://www.npmjs.com/package/@penjc/homepage)
[![npm downloads](https://img.shields.io/npm/dm/@penjc/homepage?style=flat-square)](https://www.npmjs.com/package/@penjc/homepage)
[![Vercel](https://img.shields.io/badge/Deploy_on-Vercel-black?style=flat-square&logo=vercel)](https://vercel.com)
[![Netlify](https://img.shields.io/badge/Deploy_on-Netlify-00c7b7?style=flat-square&logo=netlify)](https://netlify.com)
<!-- [![GitHub Pages](https://img.shields.io/badge/Deploy_on-GitHub_Pages-222?style=flat-square&logo=github)](https://pages.github.com/) -->

[//]: # ([![GitHub stars]&#40;https://img.shields.io/github/stars/penjc/homepage?style=flat-square&#41;]&#40;https://github.com/penjc/homepage/stargazers&#41;)

[//]: # ([![GitHub forks]&#40;https://img.shields.io/github/forks/penjc/homepage?style=flat-square&#41;]&#40;https://github.com/penjc/homepage/network/members&#41;)

[//]: # ([![GitHub issues]&#40;https://img.shields.io/github/issues/penjc/homepage?style=flat-square&#41;]&#40;https://github.com/penjc/homepage/issues&#41;)

[//]: # ([![GitHub license]&#40;https://img.shields.io/github/license/penjc/homepage?style=flat-square&#41;]&#40;https://github.com/penjc/homepage/blob/main/LICENSE&#41;)

[![Next.js](https://img.shields.io/badge/Next.js-13+-black?style=flat-square&logo=next.js)](https://nextjs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
[![Tailwind CSS](https://img.shields.io/badge/Tailwind_CSS-3.0+-38bdf8?style=flat-square&logo=tailwind-css)](https://tailwindcss.com/)
[![React](https://img.shields.io/badge/React-18+-61dafb?style=flat-square&logo=react)](https://reactjs.org/)
[![Framer Motion](https://img.shields.io/badge/Framer_Motion-11+-ff0055?style=flat-square&logo=framer)](https://www.framer.com/motion/)

[//]: # ([![PRs Welcome]&#40;https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square&#41;]&#40;https://github.com/penjc/homepage/pulls&#41;)

[//]: # ([![Maintenance]&#40;https://img.shields.io/badge/Maintained%3F-yes-green.svg?style=flat-square&#41;]&#40;https://github.com/penjc/homepage/graphs/commit-activity&#41;)

[//]: # ([![Made with Love]&#40;https://img.shields.io/badge/Made%20with-❤️-red?style=flat-square&#41;]&#40;https://github.com/penjc&#41;)

[//]: # ()

**现代化、响应式的个人主页模版**

基于 Next.js 13+ 构建的全功能个人主页模板，集成博客、项目展示、书单、友链等多种功能。  
采用 TypeScript + Tailwind CSS + Framer Motion 技术栈，提供流畅的动画效果和卓越的用户体验。

[🚀 快速开始](#-快速开始) • [📖 文档](#-文档) • [🎨 特性](#-特性) • [💻 演示](https://pengjiancheng.com) • [🤝 贡献](#-贡献)

简体中文 | [English](./README.en.md)

</div>

---

## ✨ 特性

### 📝 内容管理
- 📝 **Markdown** - 支持 Markdown 写作，代码语法高亮
- 📚 **博客系统** - 完整的博客功能，支持分页、分类、标签
- ✍️ **随笔功能** - 记录生活感悟，支持心情标签
- 🔍 **搜索功能** - 内置全文搜索

### 🗂️ 展示模块
- 💼 **项目展示** - 展示个人项目作品
- 📚 **书籍管理** - 分享阅读书单，记录读书心得
- 🤝 **友链管理** - 管理友情链接
- 👤 **关于页面** - 完整的个人介绍

### 🎬 动画效果
- ✨ **入场动画** - 流畅的入场动画效果
- 🎭 **动画系统** - 元素按层次依次出现
- 🚀 **交互反馈** - 悬浮、点击等交互反馈
- ⚡ **性能优化** - 基于 Framer Motion 构建

### 🎯 互动功能
- 💬 **评论系统** - 支持多种评论系统
- 🔄 **实时更新** - 动态内容加载
- 🎨 **主题适配** - 评论系统自动适配网站主题

### 🚀 部署与开发
- 🚀 **一键部署** - 支持 Vercel、Netlify 等平台
- ⚙️ **配置驱动** - 通过配置文件管理所有功能
- 🔧 **开发友好** - 热重载、ESLint、Prettier 开箱即用
- 📦 **模块化设计** - 组件化架构，易于定制和扩展

### ⚡ 性能与技术
- ⚡ **极速性能** - 基于 Next.js 13+ 构建，静态生成
- 🎯 **SEO 优化** - 内置 SEO 最佳实践
- 📱 **PWA 支持** - 支持离线访问，可安装到桌面
- 🔧 **TypeScript** - 完整的类型安全

## 🚀 快速开始

### 方式一：使用 npx

```bash
# 创建新项目
npx @penjc/homepage my-website

# 进入项目目录
cd my-website

# 启动开发服务器
npm run dev
```

### 方式二：克隆仓库

```bash
# 克隆仓库
git clone https://github.com/penjc/homepage.git my-website

# 进入项目目录
cd my-website

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

访问 [http://localhost:4000](http://localhost:4000) 查看你的网站。

## 📖 文档

### 🛠️ 开发命令

```bash
npm run dev      # 启动开发服务器 (http://localhost:4000)
npm run build    # 构建生产版本
npm run start    # 启动生产服务器
npm run lint     # 代码检查
```

### ⚙️ 配置网站

修改 `site.config.example.ts` 为`ste.config.ts`。

编辑 `site.config.ts` 文件来配置你的网站：

```typescript
export const siteConfig = {
  // 基本信息
  name: "你的名字",
  title: "你的网站标题",
  description: "你的网站描述",
  url: "https://yourdomain.com",
  
  // 个人信息
  profile: {
    avatar: "/images/avatar.jpg",
    bio: "你的个人简介",
    email: "your.email@example.com",
    github: "https://github.com/yourusername",
    social: {
      linkedin: "https://linkedin.com/in/username",
      twitter: "https://twitter.com/username",
      // ... 更多社交媒体链接
    }
  },
  
  // 导航配置
  navigation: {
    main: [
      { name: "首页", href: "/" },
      { name: "博客", href: "/blog" },
      { name: "随笔", href: "/thoughts" },
      { name: "关于", href: "/about" },
    ],
  }
}
```

### 📝 添加内容

#### 博客文章

在 `content/blog/` 目录下创建 `.md` 文件：

```markdown
---
title: 标题
date: "2025-06-04"
category: "生活"
tags: ["个人主页", "Next.js"]
excerpt: "这是我的第一篇博客文章，欢迎来到我的个人主页！"
readTime: "3分钟"
---

# 文章内容

这里是文章的正文内容...
```

#### 随笔

在 `content/thoughts/` 目录下创建 `.md` 文件：

```markdown
---
date: "2025-06-04"
mood: "🌧️"
tags: ["感悟"]
---

# 随笔内容

这里是随笔的内容...
```

#### 图片资源

将图片文件放在 `public/images/` 目录下，然后在文章中引用：

```markdown
![图片描述](/images/your-image.jpg)
```

### 🗂️ 配置展示模块

#### 项目展示

在 `site.config.ts` 中配置项目信息：

```typescript
projects: {
  enabled: true,
  title: "项目",
  description: "探索技术作品与创新项目",
  items: [
    {
      id: "homepage",
      title: "个人主页",
      description: "基于 Next.js 的个人主页模板",
      image: "/images/projects/homepage.jpg",
      tags: ["Next.js", "TypeScript", "Tailwind CSS"],
      github: "https://github.com/username/homepage",
      demo: "https://your-site.com",
      status: "active", // active | completed | archived
      featured: true
    }
    // 更多项目...
  ]
}
```

#### 书籍管理

配置你的阅读书单：

```typescript
books: {
  enabled: true,
  title: "书籍",
  description: "分享值得阅读的好书，记录阅读心得",
  items: [
    {
      id: "clean-code",
      title: "代码整洁之道",
      author: "Robert C. Martin",
      category: "tech",
      rating: 5,
      status: "read", // reading | read | want_to_read
      cover: "/images/books/clean-code.jpg",
      description: "代码质量与其整洁度成正比...",
      review: "这本书彻底改变了我对编程的认知",
      tags: ["编程", "软件工程", "最佳实践"],
      readDate: "2024-01-15",
      featured: true,
      purchaseLinks: {
        amazon: "https://amazon.com/clean-code",
        douban: "https://book.douban.com/subject/4199741/"
      }
    }
    // 更多书籍...
  ]
}
```

#### 友链管理

配置友情链接：

```typescript
friends: {
  enabled: true,
  title: "友链",
  description: "志同道合的朋友们",
  items: [
    {
      id: "friend-1",
      name: "朋友名称",
      description: "朋友网站的描述",
      avatar: "https://avatars.githubusercontent.com/u/1?v=4",
      url: "https://friend-site.com",
      featured: true,
      status: "active", // active | inactive
      tags: ["技术", "博客", "前端"]
    }
    // 更多友链...
  ]
}
```

#### 关于页面

配置个人信息展示：

```typescript
about: {
  // 个人简介
  intro: {
    title: "个人简介",
    paragraphs: [
      "后端开发工程师。熟练掌握后端技术栈...",
      "在工作之余，我喜欢分享技术文章..."
    ]
  },
  
  // 教育背景
  education: {
    title: "教育背景",
    items: [
      {
        year: "2020 - 2024",
        degree: "计算机科学与技术 硕士",
        school: "大学名称",
        description: "专业课程描述...",
        gpa: "3.8/4.0"
      }
    ]
  },
  
  // 工作经历
  experience: {
    title: "工作经历",
    items: [
      {
        year: "2023 - 现在",
        title: "软件工程师",
        company: "公司名称",
        description: "工作描述...",
        highlights: ["工作亮点1", "工作亮点2"]
      }
    ]
  },
  
  // 技能专长
  skills: {
    title: "技能专长",
    categories: [
      {
        name: "后端开发",
        skills: [
          { name: "Java/Spring Boot", level: 95 },
          { name: "Python/Django", level: 88 }
        ]
      }
    ]
  }
}
```

### 💬 配置评论系统

支持多种评论系统，可以选择其中一种进行配置。评论功能会自动出现在博客详情页、随笔页、项目页、书籍页、友链页和关于页。

#### 支持的评论系统

- **Giscus** (推荐) - 基于 GitHub Discussions，完全免费
- **Gitalk** - 基于 GitHub Issues
- **Valine** - 基于 LeanCloud
- **Waline** - Valine 的增强版

#### 快速配置

在 `site.config.ts` 文件中配置评论系统：

```typescript
export const siteConfig = {
  // ... 其他配置
  
  comments: {
    enabled: true,               // 启用评论功能
    provider: "giscus",          // 选择评论系统: giscus | gitalk | valine | waline
    
    // Giscus 配置 (推荐)
    giscus: {
      repo: "your-username/your-repo",
      repoId: "your-repo-id",
      category: "General",
      categoryId: "your-category-id",
      mapping: "pathname",
      theme: "preferred_color_scheme",
      lang: "zh-CN",
      // ... 更多配置
    },
    
    // 其他评论系统配置...
  },
  
  // ... 其他配置
};
```

> **提示**: 仍支持环境变量配置方式，但推荐使用配置文件方式管理。

详细配置说明请查看 [评论系统配置指南](docs/COMMENTS.md)。

## 🚀 部署

### Vercel 部署（推荐）

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/penjc/homepage)

1. 点击上方按钮
2. 连接你的 GitHub 账户
3. 自动部署完成

### Netlify 部署

[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/penjc/homepage)

1. 点击上方按钮
2. 连接你的 GitHub 账户
3. 设置构建命令：`npm run build`
4. 设置发布目录：`.next`

<!-- ### GitHub Pages 部署

项目内置了 GitHub Actions 工作流，推送到 `main` 分支时会自动部署到 GitHub Pages。

#### 快速部署

1. 在仓库设置中启用 GitHub Pages
2. 选择 GitHub Actions 作为部署源
3. 推送代码到 `main` 分支即可自动部署

#### 路径配置说明

本项目针对 GitHub Pages 项目页面进行了特别优化，解决了静态资源路径问题：

- **本地开发**: 所有资源使用相对路径（如 `/favicon.svg`）
- **GitHub Pages**: 自动添加项目名前缀（如 `/homepage/favicon.svg`）

#### 构建命令

```bash
npm run build:github    # GitHub Pages 专用构建
npm run preview:github  # 预览 GitHub Pages 构建结果
```

#### 环境变量

部署过程中会自动设置以下环境变量：
- `GITHUB_PAGES=true`: 启用 GitHub Pages 模式
- `NODE_ENV=production`: 生产环境标识 -->

## 🛠️ 技术栈

- **框架**: [Next.js 13+](https://nextjs.org/) - React 全栈框架
- **样式**: [Tailwind CSS](https://tailwindcss.com/) - 实用优先的 CSS 框架
- **语言**: [TypeScript](https://www.typescriptlang.org/) - 类型安全的 JavaScript
- **图标**: [Heroicons](https://heroicons.com/) + [Lucide React](https://lucide.dev/)
- **动画**: [Framer Motion](https://www.framer.com/motion/) - 生产就绪的动画库
- **内容**: [Markdown](https://www.markdownguide.org/) + [Gray Matter](https://github.com/jonschlinkert/gray-matter)
- **代码高亮**: [Prism.js](https://prismjs.com/)

## 📁 项目结构

```
homepage/
├── app/                    # Next.js 13+ App Router
│   ├── about/             # 关于页面
│   ├── blog/              # 博客相关页面
│   ├── thoughts/          # 随笔页面
│   ├── books/             # 书籍页面
│   ├── friends/           # 友链页面
│   └── projects/          # 项目展示页面
├── components/            # React 组件
├── content/               # Markdown 内容
│   ├── blog/             # 博客文章
│   └── thoughts/         # 随笔文章
├── lib/                   # 工具函数
├── public/                # 静态资源
│   └── images/           # 图片资源
├── styles/                # 样式文件
├── site.config.ts         # 网站配置
└── package.json          # 项目依赖
```

## 🤝 贡献

我们欢迎所有形式的贡献！可参考[贡献指南](CONTRIBUTING.md)指南。

### 如何贡献

1. Fork 这个仓库
2. 创建你的特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交你的更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开一个 Pull Request

## 📄 许可证

本项目基于 [MIT 许可证](LICENSE) 开源。

## 🙏 致谢

感谢所有为这个项目做出贡献的开发者！

---

<div align="center">

**如果这个项目对你有帮助，请给一个 ⭐️支持**

Made with ❤️ by [penjc](https://pengjiancheng.com)

</div>