Language: 中文 | English | 日本語

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

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

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

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

持续迭代中

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

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

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

默认输出纯静态站，可直接部署到 Vercel、Netlify、nginx 等平台。只有启用可选的“碎碎念”动态归档时，才需要 Astro Node standalone 部署；两种模式的配置见部署架构。

也可以通过 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

启用“碎碎念”后请改用 pnpm docker:up:dynamic。该功能默认关闭，完整配置与真实链路验收见碎碎念指南。

开始前请确保已安装 Node.js 22.20.0 或更高版本，以及 pnpm 10.28.2。

1. 克隆项目到本地

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

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

cd astro-koharu
pnpm i

3. 启动项目

pnpm dev

• 基于 Astro 7.x，静态站点生成，性能优异
• 优雅的深色/浅色主题切换
• 基于 Pagefind 的无后端全站搜索
• 可更换评论系统：支持 Waline（推荐）、Giscus、Remark42、Twikoo 四种评论组件，配置文件一键切换，主题自动跟随
• 完整的 Markdown 增强功能（GFM、代码高亮、自动目录、Mermaid 图表、Infographic 信息图）
• Shoka 兼容 Markdown 语法：文字特效（下划线/高亮/上下标/颜色）、隐藏文字（Spoiler）、注音标注（Ruby）、提醒块、折叠块、标签卡、友链卡片、音视频播放器、练习题系统（单选/多选/判断/填空）、数学公式（KaTeX）、代码块增强（title/mark/command）—— 所有功能均可独立开关
• [可开关] 内容加密：支持文章局部加密（加密块）和整篇文章加密（加密文章），使用 AES-256-GCM 客户端解密，密码仅在构建时使用、不传递到客户端
• 灵活的多级分类与标签系统
• [可开关] 多系列文章支持（周刊、书摘等自定义系列，支持自定义 URL slug）

  💡 说明：featuredSeries 适合文章数量较多的分类，将其从首页主列表分离以避免刷屏。系列文章仅最新一篇在首页高亮，其余通过系列专属页面访问，但在归档、分类、标签等页面仍正常展示。

• [可开关] 追番页面（Bangumi）：接入 Bangumi API，展示动画/书籍/音乐/游戏收藏，支持分类切换、状态筛选、分页浏览，数据实时获取
• [可开关] 碎碎念动态归档：从 koharu-suite 的公开频道读取消息，提供频道、详情、搜索、cursor 分页和 branded RSS；默认静态部署完全不受影响，详见配置指南
• 独立页面系统：在 src/pages/ 下创建 .md 文件即可添加自定义页面（关于、歌单等），支持自定义封面标题和评论开关
• 响应式设计
• 草稿与置顶功能
• 阅读进度条与阅读时间估算
• 智能目录导航，支持 CSS 计数器自动编号（可按文章关闭）
• 移动端文章阅读头部（显示当前章节标题、圆形阅读进度、可展开目录）
• 友链系统与归档页面
• 多语言支持（i18n）：内置中英文 UI 翻译，支持自定义语言包、内容级翻译（分类名/系列名）、语言切换器、hreflang SEO 标签、locale-aware RSS 订阅。默认语言 URL 无前缀，其他语言自动加前缀（如 /en/post/xxx）
• RSS 订阅支持
• 支持 LQIP：图片加载前显示渐变色占位，提升视觉体验
• [可开关] 基于语义相似度的智能文章推荐系统，使用 transformers.js 在本地生成文章嵌入向量，计算文章间的语义相似度
• [可开关] AI 自动摘要生成，自动生成摘要。
• [可开关] 圣诞特辑：包含雪花飘落、圣诞配色、圣诞帽装饰、灯串装饰等节日氛围效果
• 无后端站点公告系统：可通过配置文件管理公告，支持时间控制、多条公告堆叠、自定义颜色、hover 已读
• 有样式的 RSS 订阅源链接
• Koharu CLI：交互式命令行工具，支持备份/还原、内容生成、备份管理
• 本地轻 CMS 应用：运行 pnpm cms 启动独立的 CMS 管理界面，支持文章管理、浏览器内编辑、Markdown 预览等功能。文章页的编辑按钮支持一键跳转到本地编辑器（VS Code / Cursor / Zed），配置见 config/site.yaml 的 dev 部分。(后期会考虑做个有后端的版本，这期先静态)

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

pnpm koharu              # 交互式主菜单
pnpm koharu new          # 新建内容（文章/友链）
pnpm koharu backup       # 备份博客内容和配置
pnpm koharu restore      # 从备份恢复
pnpm koharu update       # 更新主题
pnpm koharu migrate      # 一键迁移历史文章数据
pnpm koharu generate     # 生成内容资产 (LQIP, 相似度, AI 摘要)
pnpm koharu clean        # 清理旧备份
pnpm koharu list         # 查看所有备份

快速创建博客文章和友链：

# 交互式选择创建类型
pnpm koharu new

# 或直接指定类型
pnpm koharu new post     # 新建博客文章（交互式输入标题、分类、标签等）
pnpm koharu new friend   # 新建友情链接（自动追加到 config/site.yaml）

新建文章功能：

• 自动生成拼音 slug
• 选择已有分类
• 支持多标签
• 检查文件重复
• 自动创建 frontmatter

新建友链功能：

• 交互式输入友站信息
• 自动追加到配置文件
• 保留 YAML 格式和注释

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

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

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

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

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

升级到 Astro 6 或还原旧备份后，必须在运行 pnpm dev 或 pnpm build 前迁移文章链接。从旧版升级时， 请先等 pnpm koharu update 进程完全退出，再执行：

pnpm koharu migrate --dry-run
pnpm koharu migrate

迁移会先自动创建基础备份，保留已有 link，将旧 slug 安全转换为 link，并为缺少两者的文章补充稳定链接。 脚本可重复执行；发现重复链接或无法安全处理的 frontmatter 时会停止且不修改文件。通过 Koharu CLI 还原旧备份时会自动执行同一迁移。 pnpm dev 和 pnpm build 也会先执行只读检查，在内容尚未迁移时停止并显示修复命令。

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

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

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

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

# 更新到指定版本
pnpm koharu update --tag v2.1.0

# clean 模式（零冲突，强制备份，适合首次迁移或冲突较多时）
pnpm koharu update --clean

# rebase 模式（重写历史，强制备份，适合熟悉 git 的用户）
pnpm koharu update --rebase

# 预览操作（不实际执行）
pnpm koharu update --dry-run

💡 更新模式说明：

• 默认模式：使用 git merge --no-ff 合并上游更新，保留 merge-base 信息。遇到用户内容（博客文章、配置等）冲突时自动保留本地版本，仅主题文件冲突需手动解决。
• Clean 模式 (--clean)：用上游最新版本替换所有主题文件，然后从备份还原用户内容，实现零冲突更新。适合首次从旧版迁移或冲突较多时使用。注意：用户对主题文件的自定义修改不会被保留。
• Rebase 模式 (--rebase)：将本地提交重放到上游之上，重写提交历史。适合熟悉 git 的用户。

CLI 更新命令是对 git 操作的封装，熟悉 git 的用户也可以直接使用 git merge/git rebase 手动操作。

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

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

项目将 .cache/og-data.json 提交到 Git 仓库，用于缓存链接嵌入功能抓取的 OG 元数据（标题、描述、图片等）。这样在 Vercel、Netlify 等平台构建时可以直接复用已有缓存，避免每次构建都重新抓取外部链接的元信息，显著加速构建并减少对外部站点的请求。

.cache/ 目录下的其他文件（如 transformers 模型缓存）仍被 .gitignore 忽略。

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

• 站点基本信息（标题、副标题、作者等）
• 社交媒体链接
• 导航菜单
• 特色分类和周刊配置
• 分类映射（中文分类名 → URL slug）
• 友链列表
• 公告系统
• 评论系统（Waline / Giscus / Remark42 / Twikoo，推荐使用 Waline）
• 数据统计（Umami）
• 国际化配置（i18n）
• 背景音乐（BGM）：配置 bgm.audio 添加歌单，bgm.metingApi 可自定义 Meting API 地址（默认 https://163.hyc.moe/，推荐自部署）
• 追番页面（Bangumi）：配置 bangumi.userId 即可开启，注释掉整段关闭
• 圣诞特辑开关
• 开发工具配置（config/site.yaml 的 dev 部分，用于本地编辑器跳转）

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

在 config/site.yaml 的 i18n 部分配置支持的语言：

i18n:
  defaultLocale: zh # 默认语言（URL 无前缀）
  locales:
    - code: zh
      label: 中文
    - code: en
      label: English

内容翻译：在 config/i18n-content.yaml 中配置分类名、系列名等内容级字符串的翻译：

en:
  categories:
    life: Life
    note: Notes
    tools: Tools
  series:
    weekly:
      label: My Weekly
      fullName: My Tech Weekly

添加翻译文章：将翻译文章放在 src/content/blog/<locale>/ 目录下，保持与默认语言相同的路径结构：

src/content/blog/
├── tools/getting-started.md        # 默认语言 (zh)
├── en/tools/getting-started.md     # 英文翻译
└── en/life/hello-world.md          # 英文翻译

没有对应翻译的文章会自动回退显示默认语言内容，并标注提示。

添加新语言：

1. 在 config/site.yaml 的 i18n.locales 中添加新语言
2. 创建 src/i18n/translations/<code>.ts，按需翻译 UI 字符串（未翻译的 key 会回退到默认语言）
3. 在 src/i18n/translations/index.ts 中注册新语言
4. 在 config/i18n-content.yaml 中添加内容翻译（可选）

在 config/site.yaml 中通过 comment.provider 字段一键切换评论系统：

comment:
  provider: waline # 'waline' | 'giscus' | 'remark42' | 'twikoo' | 'none'
  waline:
    serverURL: https://your-waline-server.vercel.app
    # ... 其他配置

推荐使用 Waline：自部署简单、功能丰富（Markdown、表情、邮件通知）、带访问量统计。详细配置请参考完整使用指南。

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

• 图片加载前显示渐变色占位，提升视觉体验 - 介绍文章
• 使用 view-transition 实现的流畅的深色模式切换主题过渡动画。
• Markdown 增强 - 链接嵌入功能 - 示例
• Markdown 增强 - 使用 @antv/infographic 创建各种精美的信息图表。 Infographic 信息图指南
• 有样式的 RSS 订阅源链接 - 示例
• 公告系统
• Shoka 兼容 Markdown 语法 - 提醒块、折叠块、标签卡、文字特效、隐藏文字、注音标注、练习题等
• 音视频播放器 - 支持音乐歌单和视频播放，通过 Meting API 解析，推荐自部署

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

使用字体寒蝉全圆体

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

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

...

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