astro-koharu

astro-koharu is an Astro-based static blog theme with a cute ACG pink-blue aesthetic, designed for personal blogs and inspired by the Hexo Shoka theme.

What is astro-koharu?

astro-koharu is a blog theme built on Astro 7.x that generates pure static sites. It takes Markdown content from src/content/blog and configuration from config/site.yaml as input, and produces a fast, deployable static website with features like full-site search, RSS, and multi-language support. The theme is developed by cosine and released under the AGPL-3.0 license. It is designed to be lightweight and performant, with an optional dynamic mode for the "碎碎念" (moments) feature that requires an Astro Node standalone deployment.

Key Features

• Framework and tech stack — Built with Astro 7.x, using React and Tailwind CSS, with TypeScript support; outputs pure static files deployable to Vercel, Netlify, nginx, or Docker with Nginx.
• No-backend search — Integrates Pagefind to provide full-site search without any server-side component.
• Pluggable comment systems — Supports Waline, Giscus, Remark42, and Twikoo; switch providers by changing the comment.provider field in config/site.yaml.
• Shoka-compatible Markdown enhancements — Implements text effects (underline, highlight, sub/superscript, colors), spoilers, ruby annotations, alert blocks, collapsible blocks, tag cards, friend-link cards, audio/video players, an exercise system (single/multiple choice, true/false, fill-in-blank), KaTeX math, and enhanced code blocks, each toggleable.
• Content encryption — Optional AES-256-GCM client-side decryption for encrypted blocks or full posts; passwords are used only at build time and never sent to the client.
• Internationalization (i18n) — Built-in Chinese and English UI translations, content-level translations for category and series names, a language switcher, hreflang SEO tags, and locale-aware RSS feeds (default language URL is prefixless, others get /en/ style prefixes).
• Bangumi integration — Optional "追番" page that pulls anime, book, music, and game collections from the Bangumi API (bgm.tv), with category tabs, status filters, and pagination.
• Koharu CLI — Interactive command-line tool for creating posts and friend links, backing up and restoring content, updating the theme, migrating legacy data, and generating LQIP placeholders, similarity vectors, and AI summaries.
• Local CMS — Running pnpm cms launches a local management interface for editing posts, Markdown preview, and one-click jumping to editors like VS Code, Cursor, or Zed.

Who is it for?

• ACG bloggers — Set up a pink-blue themed personal blog to share anime, manga, and game-related posts, with Bangumi integration to display their collections.
• Front-end developers — Use the flexible Markdown enhancements, code block features, and local CMS to write technical articles and customize the theme with React components.
• Journaling and life-blog writers — The cute design and support for friend links, series, and announcements make it suitable for personal diaries and 手账-style content.
• Self-hosters — Deploy the static site to any platform or use the provided Docker setup with Nginx, with optional analytics via Umami.

What can you do with astro-koharu?

• Create a multilingual blog — Write posts in Chinese and English, add translations in src/content/blog/en/, and let the theme handle language switching, hreflang tags, and locale-specific RSS.
• Encrypt private posts — Use the content encryption feature to protect individual blocks or entire articles with AES-256-GCM, decrypting only in the client browser.
• Automate content management — Use the Koharu CLI to scaffold new posts with auto-generated pinyin slugs, manage friend links, and back up all content before theme updates.
• Display a media collection — Enable the Bangumi page to showcase your anime, book, music, and game lists, with real-time data from the Bangumi API.

How does astro-koharu work?

The theme works like a standard Astro project: clone the repository, install dependencies with pnpm, and run pnpm dev for local development. Content is written as Markdown files with frontmatter in src/content/blog, and site-wide configuration is edited in config/site.yaml. For production, run pnpm build to generate a static site, or use the provided Docker scripts to build an Nginx container. The optional dynamic "moments" feature requires an Astro Node standalone adapter.

Pros and cons

• Pros: Optimized for performance with LQIP image placeholders and a PageSpeed target of all-green; no backend required for the default feature set; highly configurable with per-feature toggles.
• Cons: Requires Node.js 22.20.0 or higher and pnpm 10.28.2; enabling the Moments feature means you cannot use pure static hosting and must run an Astro Node standalone server.

Alternatives

• Hexo Shoka — The Hexo theme that inspired astro-koharu's visual design and compatibility with Shoka Markdown syntax; it runs on the Node-based Hexo static site generator instead of Astro.

FAQ

Is astro-koharu free?

Yes, astro-koharu is open source under the GNU Affero General Public License version 3 (AGPL-3.0). You can freely use, modify, and fork it for personal or commercial projects, provided you share derivative source code under the same license.

Which comment systems does astro-koharu support?

It supports four comment systems: Waline (recommended), Giscus, Remark42, and Twikoo. You can switch between them by editing the comment.provider field in config/site.yaml. The theme automatically follows the chosen provider's style.

Does astro-koharu require a backend server?

No, the default deployment is fully static and can be hosted on Vercel, Netlify, or nginx. The only exception is the optional "碎碎念" dynamic moments feature, which requires an Astro Node standalone deployment to read messages from a koharu-suite channel.

How do I update astro-koharu?

Use the built-in Koharu CLI command pnpm koharu update, which automatically backs up, pulls upstream changes, merges, and installs dependencies. You can also use clean or rebase modes for zero-conflict updates, or manually run git merge/rebase if you prefer.