# qiuhexo-template

**Repository Path**: qiustudio/qiuhexo-template

## Basic Information

- **Project Name**: qiuhexo-template
- **Description**: QIUHEXO博客基本模板
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-02-22
- **Last Updated**: 2026-02-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QiuHexo 主题模板

> 一个简约、美观、响应式的 Hexo 主题模板

## 项目概述

QiuHexo 是一个基于 Hexo 的现代化博客主题，采用简约设计风格，支持亮色/暗色模式切换，响应式布局适配各种设备，提供丰富的功能和良好的用户体验。

## 特色功能

- **响应式设计**：适配桌面端、平板和移动设备
- **亮色/暗色模式**：支持自动切换和手动切换
- **现代化布局**：简洁美观的界面设计
- **丰富的页面类型**：首页、文章页、分类页、标签页、关于页、友链页
- **代码高亮**：集成 Prism.js 实现代码语法高亮
- **图片预览**：集成 FancyBox 实现图片点击放大预览
- **平滑滚动**：实现页面内平滑滚动效果
- **分类标签**：支持文章分类和标签管理
- **导航菜单**：响应式导航菜单，移动端自动折叠
- **主题配置**：丰富的配置选项，支持个性化定制
- **SEO 友好**：优化页面结构，提升搜索引擎排名
- **性能优化**：代码压缩，资源加载优化

## 技术栈

- **Hexo**：静态网站生成器
- **EJS**：模板引擎
- **Stylus**：CSS 预处理器
- **JavaScript**：交互功能实现
- **CSS 变量**：实现主题配色管理
- **媒体查询**：实现响应式布局
- **YAML**：配置文件格式

## 安装与配置

### 前提条件

- Node.js 14.0 或更高版本
- npm 6.0 或更高版本
- Git

### 安装步骤

1. **克隆项目**

   ```bash
   git clone <repository-url> qiuhexo-blog
   cd qiuhexo-blog
   ```

2. **安装依赖**

   ```bash
   npm install
   ```

3. **配置主题**

   修改 `themes/qiuhexo/_config.yml` 文件，根据需要配置主题选项：

   ```yaml
   # 菜单配置
   menu:
     首页: /
     分类: /categories
     标签: /tags
     关于: /about
     友链: /friends

   # 头部配置
   header:
     title: QiuHexo
     subtitle: A modern Hexo theme

   # 布局配置
   layout:
     width: 1000px
     sidebar: true

   # 主题模式
   theme:
     default: light  # light 或 dark
     auto: true      # 自动根据系统设置切换
   ```

4. **创建必要页面**

   创建关于页：
   ```bash
   hexo new page about
   ```

   创建友链页：
   ```bash
   hexo new page friends
   ```

5. **启动本地服务器**

   ```bash
   hexo server
   ```

   访问 `http://localhost:4000` 查看效果

6. **构建静态文件**

   ```bash
   hexo clean && hexo generate
   ```

   构建后的文件将生成在 `public` 目录中

## 主题结构

```
themes/qiuhexo/
├── _config.yml          # 主题配置文件
├── layout/              # 模板文件
│   ├── _partial/        # 局部模板
│   │   ├── header.ejs   # 头部模板
│   │   ├── footer.ejs   # 底部模板
│   │   ├── menu.ejs     # 菜单模板
│   │   └── ...
│   ├── index.ejs        # 首页模板
│   ├── post.ejs         # 文章页模板
│   ├── page.ejs         # 页面模板
│   ├── categories.ejs   # 分类页模板
│   ├── tags.ejs         # 标签页模板
│   └── ...
└── source/              # 静态资源
    ├── css/             # CSS 文件
    │   ├── main.styl    # 主样式文件
    │   └── ...
    ├── js/              # JavaScript 文件
    │   ├── theme.js     # 主题切换脚本
    │   └── ...
    └── ...
```

## 开发与定制

### 模板开发

主题使用 EJS 模板引擎，模板文件位于 `themes/qiuhexo/layout/` 目录。您可以根据需要修改模板文件，添加或删除功能。

### 样式定制

主题使用 Stylus CSS 预处理器，样式文件位于 `themes/qiuhexo/source/css/` 目录。主要样式文件是 `main.styl`，您可以通过修改此文件来自定义主题样式。

### 主题扩展

您可以通过以下方式扩展主题功能：

1. **添加新页面模板**：在 `layout/` 目录中创建新的模板文件
2. **添加新的局部模板**：在 `layout/_partial/` 目录中创建新的局部模板
3. **添加新的静态资源**：在 `source/` 目录中添加新的静态资源
4. **修改主题配置**：在 `_config.yml` 文件中添加新的配置选项

## 配置选项

### 基本配置

- **menu**：导航菜单配置
- **header**：头部配置（标题、副标题等）
- **index**：首页配置（文章数量、布局等）
- **layout**：全局布局配置（宽度、侧边栏等）
- **post**：文章页配置（评论、分享等）
- **about**：关于页配置
- **friends**：友链页配置

### 主题模式配置

- **theme.default**：默认主题模式（light 或 dark）
- **theme.auto**：是否自动根据系统设置切换主题

### 其他配置

- **favicon**：网站图标
- **keywords**：网站关键词
- **description**：网站描述
- **analytics**：网站统计代码

## 使用指南

### 创建文章

```bash
hexo new "文章标题"
```

文章头部配置示例：

```yaml
title: 文章标题
date: 2026-02-23 10:00:00
categories:
  - 技术
tags:
  - Hexo
  - 主题
---

文章内容...
```

### 配置友链

编辑 `source/friends/index.md` 文件，添加友链信息：

```yaml
title: 友链
date: 2026-02-23 10:00:00
---

{% friends %}
- name: 朋友1
  url: https://example.com
  description: 朋友1的博客
- name: 朋友2
  url: https://example.org
  description: 朋友2的网站
{% endfriends %}
```

### 配置关于页

编辑 `source/about/index.md` 文件，添加个人信息：

```yaml
title: 关于我
date: 2026-02-23 10:00:00
---

# 个人简介

这里是个人简介内容...

## 技能

- HTML/CSS
- JavaScript
- Node.js
- Hexo
```

## 常见问题

### 如何修改主题配色？

修改 `themes/qiuhexo/source/css/main.styl` 文件中的 CSS 变量：

```styl
:root
  --primary-color: #3498db
  --secondary-color: #2ecc71
  --text-color: #333
  --background-color: #fff
  
.dark-theme
  --primary-color: #3498db
  --secondary-color: #2ecc71
  --text-color: #eee
  --background-color: #121212
```

### 如何添加新的菜单项？

修改 `themes/qiuhexo/_config.yml` 文件中的 `menu` 配置：

```yaml
menu:
  首页: /
  分类: /categories
  标签: /tags
  关于: /about
  友链: /friends
  新页面: /new-page
```

### 如何禁用自动主题切换？

修改 `themes/qiuhexo/_config.yml` 文件中的 `theme.auto` 配置：

```yaml
theme:
  default: light
  auto: false
```

## 浏览器兼容性

- Chrome 60+
- Firefox 55+
- Safari 12+
- Edge 79+

## 贡献

欢迎提交 Issue 和 Pull Request 来改进主题！

## 许可证

MIT License

## 致谢

- [Hexo](https://hexo.io/)
- [Prism.js](https://prismjs.com/)
- [FancyBox](https://fancyapps.com/fancybox/3/)

## 联系

- 作者：Qiu
- GitHub：<repository-url>

---

**享受使用 QiuHexo 主题！** 🎉