astro-koharu

一个萌系 / 二次元 / 粉蓝配色的博客主题，适合 ACG、前端、手账向个人站，性能优异。

命名灵感来源于 “小春日和”（こはるびより）指的是晚秋到初冬这段时期，持续的一段似春天般温暖的晴天。也就是中文中的"小阳春"。

博客整体设计灵感来自 Hexo 的 Shoka 主题，用更现代的技术栈打造属于你的个人博客。

本仓库已清理为示例仓库，主题开发者的博客可查看 https://blog.cosine.ren/ 喜欢的话欢迎 star ～

持续迭代中

• 基于 Astro，静态输出，加载轻快
• 萌系 / 二次元 / 粉蓝配色，适合 ACG、前端、手账向个人站
• 支持多分类、多标签，但不会强迫你用复杂信息架构
• 尽可能的减少性能开销
• 使用 pagefind 实现无后端的全站搜索
• LQIP（低质量图片占位符），图片加载前显示渐变色占位

性能优异：目标是 PC 的全绿，但是随着功能迭代不可避免的需要反复检查！

可在此进行博客的反馈以及查看 Roadmap，当然更欢迎在 issue 区域提 issue，不过这毕竟是个人项目，喜欢的也欢迎 fork 出去改。

部署

Vercel 一键部署

Docker 部署

也可以通过 docker / docker-compose 运行一个带 Nginx 的容器：

1. 编辑 config/site.yaml，配置 comment.remark42 和 analytics.umami 部分。
2. 执行 ./docker/rebuild.sh，脚本会自动停止旧容器并重新构建/启动。

想自定义环境文件位置或跳过 docker compose down，可在运行脚本时设置 ENV_FILE=/path/to/.env 或 SKIP_DOWN=true。

若需要手动运行 Compose，可在仓库根目录执行：

docker compose --env-file ./.env -f docker/docker-compose.yml up -d --build

本地开发

1. 克隆项目到本地

git clone https://github.com/cosZone/astro-koharu

2. 进入项目目录并安装依赖

cd astro-koharu
pnpm i

3. 启动项目

pnpm dev

功能特性

• 基于 Astro 5.x，静态站点生成，性能优异
• 优雅的深色/浅色主题切换
• 基于 Pagefind 的无后端全站搜索
• 完整的 Markdown 增强功能（GFM、代码高亮、自动目录、Mermaid 图表、Infographic 信息图）
• 灵活的多级分类与标签系统
• [可开关] 特色周刊/系列文章支持
• 响应式设计
• 草稿与置顶功能
• 阅读进度条与阅读时间估算
• 智能目录导航，支持 CSS 计数器自动编号（可按文章关闭）
• 移动端文章阅读头部（显示当前章节标题、圆形阅读进度、可展开目录）
• 友链系统与归档页面
• RSS 订阅支持
• 支持 LQIP：图片加载前显示渐变色占位，提升视觉体验
• [可开关] 基于语义相似度的智能文章推荐系统，使用 transformers.js 在本地生成文章嵌入向量，计算文章间的语义相似度
• [可开关] AI 自动摘要生成，自动生成摘要。
• [可开关] 圣诞特辑：包含雪花飘落、圣诞配色、圣诞帽装饰、灯串装饰等节日氛围效果
• 无后端站点公告系统：可通过配置文件管理公告，支持时间控制、多条公告堆叠、自定义颜色、hover 已读
• 有样式的 RSS 订阅源链接
• Koharu CLI：交互式命令行工具，支持备份/还原、内容生成、备份管理

Koharu CLI

博客自带交互式 CLI 工具，方便管理博客内容：

pnpm koharu              # 交互式主菜单
pnpm koharu backup       # 备份博客内容和配置
pnpm koharu restore      # 从备份恢复
pnpm koharu update       # 更新主题
pnpm koharu generate     # 生成内容资产 (LQIP, 相似度, AI 摘要)
pnpm koharu clean        # 清理旧备份
pnpm koharu list         # 查看所有备份

备份与还原

更新主题前，使用 CLI 备份你的个人内容：

# 基础备份（博客文章、配置、头像、.env）
pnpm koharu backup

# 完整备份（包含所有图片和生成的资产）
pnpm koharu backup --full

# 还原最新备份
pnpm koharu restore --latest

# 预览将要还原的文件（不实际还原）
pnpm koharu restore --dry-run

更新主题

使用 CLI 自动更新主题（会自动备份 → 拉取 → 合并 → 安装依赖）：

# 完整更新流程（默认会先备份）
pnpm koharu update

# 仅检查更新
pnpm koharu update --check

# 跳过备份直接更新
pnpm koharu update --skip-backup

内容生成

# 交互式选择生成类型
pnpm koharu generate

# 或直接指定类型
pnpm koharu generate lqips        # 生成 LQIP 图片占位符
pnpm koharu generate similarities # 生成相似度向量
pnpm koharu generate summaries    # 生成 AI 摘要
pnpm koharu generate all          # 生成全部

配置说明

博客配置统一使用 config/site.yaml 文件管理，包括：

• 站点基本信息（标题、副标题、作者等）
• 社交媒体链接
• 导航菜单
• 特色分类和周刊配置
• 分类映射（中文分类名 → URL slug）
• 友链列表
• 公告系统
• 评论系统（Remark42）
• 数据统计（Umami）
• 圣诞特辑开关

详细配置说明请参考文档。

文档

• 快速开始 - 启动你的博客
• 更新主题 - 如何安全地更新到新版本
• 完整使用指南 - 所有功能的详细配置和使用方法

特色功能演示图片

• 图片加载前显示渐变色占位，提升视觉体验 - 介绍文章
• 使用 view-transition 实现的流畅的深色模式切换主题过渡动画。
• Markdown 增强 - 链接嵌入功能 - 示例
• Markdown 增强 - 使用 @antv/infographic 创建各种精美的信息图表。 Infographic 信息图指南
• 有样式的 RSS 订阅源链接 - 示例
• 公告系统

使用本主题的博客

学习纸鹿的博客，我也弄一个放谁在用我的主题的区域。
欢迎加入 Q 群 598022684 进行讨论，或者在我的前端频道的评论区群聊讨论。

博客名称	作者	仓库	特色功能 or 备注
余弦の博客	cosine	cosZone/astro-koharu	本主题
雪花的博客	XueHua-s	XueHua-s/astro-snow	精简了很多功能，增加了起始页

🙏 鸣谢

使用字体寒蝉全圆体

感谢以下项目对 astro-koharu 的开发提供的灵感及参考：

• mx-space
• Hexo 主题 Shoka
• waterwater.moe
• yfi.moe
• 4ark.me
• 纸鹿摸鱼处

...

Star History

License

GNU Affero General Public License version 3 (AGPL-3.0)