hexo-theme-halunhaku
Version:
A modern, responsive Hexo theme with enhanced code blocks, perfect cover images, and Chinese text optimization. Production-ready with mobile-first design.
239 lines (177 loc) • 6.28 kB
Markdown
# Hexo Theme Halunhaku
[](https://badge.fury.io/js/hexo-theme-halunhaku)
[](https://opensource.org/licenses/MIT)
[](https://hexo.io)
[](https://github.com/forhalunhaku/hexo-theme-halunhaku)
A modern, responsive Hexo theme with multiple layout styles inspired by contemporary design patterns. **Version 2.0** brings major improvements in functionality, user experience, and code quality.
## 🎨 Demo
- [Live Demo](https://blog.halunhaku.top)
- [Documentation](https://blog.halunhaku.top/2025/07/26/hexo-theme-halunhaku-guide/)
## ✨ Features
### 🎨 Design & Layout
- **Multiple Layout Styles**: Different color schemes for home, category, and tag pages
- **Fully Responsive**: Optimized for all device sizes with mobile-first approach
- **Modern UI**: Clean, contemporary design with smooth animations
- **Perfect Cover Images**: Complete image display without cropping on all pages
### 💻 Code & Development
- **Enhanced Code Blocks**: Professional syntax highlighting with single copy button
- **Smart Copy System**: Advanced clipboard integration with visual feedback
- **No Duplicate Buttons**: Resolved conflicts with Hexo's built-in highlighter
- **Developer Tools**: Automated sync system for seamless development
### 🌏 Internationalization
- **Chinese Text Optimized**: Perfect display for Chinese characters in titles
- **Multi-language Support**: Proper text rendering for various languages
- **Typography Excellence**: Optimized line heights and character spacing
### ⚡ Performance & Technical
- **Fast Loading**: Built with Tailwind CSS and optimized assets
- **SEO Friendly**: Semantic HTML structure with proper meta tags
- **Modular CSS**: Clean, maintainable stylesheet architecture
- **Modern JavaScript**: ES6+ with proper error handling
## Installation
### Method 1: NPM (Recommended)
```bash
cd your-hexo-site
npm install hexo-theme-halunhaku
```
### Method 2: Git Clone
```bash
cd your-hexo-site
git clone https://github.com/forhalunhaku/hexo-theme-halunhaku themes/halunhaku
```
### Configuration
1. Update your site's `_config.yml`:
```yaml
theme: halunhaku
```
2. Copy theme configuration:
```bash
cp themes/halunhaku/_config.example.yml _config.halunhaku.yml
```
3. Generate and serve:
```bash
hexo clean && hexo generate && hexo server
```
## Configuration
Copy the theme's `_config.yml` to your site root and customize:
```yaml
# Theme settings
theme_style: "light" # light, dark, auto
# Site settings
site_title: "Your Blog Title"
site_subtitle: "Your blog subtitle"
# Navigation
menu:
Home: /
Categories: /categories/
Tags: /tags/
# Layout settings
posts_per_page: 6
excerpt_length: 150
```
## Page Layouts
### Home Page (Light Theme)
- Clean, bright design with blue accents
- Grid layout for posts
- Pagination support
### Category Pages (Dark Theme)
- Dark theme with purple accents
- Two-column layout with sidebar
- Popular posts and category navigation
### Tag Pages (Dark Theme)
- Dark theme with blue-purple accents
- Horizontal post layout
- Tag cloud and recent posts sidebar
### Post Pages
- Clean, readable layout
- Support for cover images
- Navigation between posts
- Tag display
## Front Matter
Add these fields to your post front matter for best results:
```yaml
---
title: Your Post Title
date: 2024-01-01
categories:
- Technology
tags:
- web-development
- design
cover: /images/post-cover.jpg
excerpt: A brief description of your post
---
```
## Customization
### Color Schemes
Edit the `color_schemes` section in `_config.yml`:
```yaml
color_schemes:
home:
primary: "#0c7ff2"
secondary: "#f3f4f6"
background: "#ffffff"
text_primary: "#111827"
text_secondary: "#6b7280"
border: "#e5e7eb"
```
### Adding Custom CSS
Create a `source/css/custom.css` file in your theme directory for additional styles.
## Development
To modify the theme:
1. Edit EJS templates in the `layout/` directory
2. Modify styles in `source/css/style.css`
3. Add helper functions in `scripts/helpers.js`
## Browser Support
- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
## License
MIT License - feel free to use and modify as needed.
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request
## Testing the Theme
Use the built-in test commands to verify everything is working:
```bash
# Test theme functionality
hexo theme:test
# Create sample content for testing
hexo theme:sample
```
## Troubleshooting
### Common Issues
1. **"Cannot GET /categories/" Error**
- Make sure `scripts/generators.js` is in your theme directory
- Restart Hexo server: `hexo clean && hexo server`
- Check that you have posts with categories
2. **Colors not displaying correctly**
- Verify `_config.halunhaku.yml` exists in site root
- Check color scheme configuration
- Restart server after config changes
3. **Posts not showing**
- Ensure posts have proper front matter
- Check date format in posts
- Verify posts are in `source/_posts/` directory
4. **Theme not loading**
- Confirm `theme: halunhaku` in main `_config.yml`
- Check theme directory name matches exactly
- Verify all theme files are present
### Debug Mode
Enable debug mode in your `_config.yml`:
```yaml
debug: true
```
### Getting Help
1. Run `hexo theme:test` to diagnose issues
2. Check your theme configuration in `_config.halunhaku.yml`
3. Open an issue on GitHub with:
- Your Hexo version (`hexo version`)
- Your Node.js version (`node --version`)
- Error messages or screenshots
- Your configuration files
## Support
If you encounter any issues or have questions, please open an issue on GitHub.