Typecho-Butterfly: the Hexo Butterfly theme running on Typecho
Hexo主题Butterfly的Typecho移植版———开源不易，帮忙点个star，谢谢了🌹
At a glance
- What is it?
- Typecho-Butterfly is a Typecho port of the popular Hexo Butterfly theme, written in PHP and distributed under Apache-2.0, with dark mode, Pjax, local search, card layouts, article encryption, comment human verification and a long checklist of features that are either implemented or explicitly still open. It is installed by unpacking a release archive into the theme directory of a Typecho blog.
- Who is it for?
- Adopt Typecho-Butterfly if you want the look and behaviour of the Hexo Butterfly theme on a Typecho blog, especially if you already have Hexo posts in markdown that you want to bring over. Do not adopt it expecting parity with the latest upstream Butterfly release, because the port explicitly lags it and your own index.css can break as a result, and note that the unfinished items include maths rendering, a photo wall and PWA support.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 117 days ago.
- What is it written in?
- Mainly PHP, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 22, 2026, and from our analysis. They are not legal advice.
Editorial analysis
Why a Typecho port of a Hexo theme exists
Typecho-Butterfly is a Typecho version of the Butterfly theme, and the original is hexo-butterfly. The README gives the reason for the port in three short sentences: the theme is good, but the author often switches devices, and the Hexo workflow is inconvenient, and some features are constrained by third party services. So they ported it.
That is a more useful origin story than most theme repositories have, because it tells you what the port is optimising for. It is not a generic theme with a Typecho name; it is a specific person's solution to a specific friction, which is why the feature list looks the way it does.
The stack details are in the badges and the environment section. The theme targets Typecho 1.2.0 and PHP 7.4 and above, and the recommended development environment is Typecho 1.3.0, PHP 8.2, PostgreSQL and NGINX, with the advice to use the same environment for running and developing to get the best experience. That is a specific and unusual recommendation, and it suggests the theme makes assumptions about the database layer and the web server.
The implementation language is PHP, the licence is Apache-2.0, and there is a live demo at blog.haoi.net with usage documentation on the same site.
Install a release, not the code archive
The installation instruction is short and comes with a warning that is worth heeding.
The README says you should preferably download from the Release page, because downloading the code from the code page may have missing updates, or may have updates applied early, either of which can make the page fail.
That is a specific and credible complaint about a theme repository that is developed in the open rather than released. The theme is deployed by copying files into a live blog, so a repository snapshot taken at an awkward moment is a broken blog, and the releases are the point at which the author considers the state coherent.
The installation itself is then a matter of downloading the archive, extracting it into the theme directory inside the blog directory, and that is the whole procedure. There is no composer step and no build step in the documentation, which is consistent with a PHP theme that ships ready to use.
The release naming is worth noting. The recent tags are v1.9.0-rc.2 from 2026-06-28, v1.9.0-rc.1 from 2026-05-13 and 1.8.1 from 2025-03-23, so the current line is release candidates rather than a stable tag, and the last push was on 2026-06-28. A cautious installer would take 1.8.1 if they want the last stable state and the 1.9.0 release candidates if they want the newest work.
What the port keeps, and the one caveat it does not hide
The porting notes list ten characteristics of the move, and one of them is a warning rather than a feature.
The first is migration. Because the posts are markdown documents in both systems, moving a blog from Hexo to Typecho is largely a matter of copying files, which removes the most painful part of changing blogging platforms.
The second is compatibility in the other direction. Existing Butterfly users can use the original Butterfly theme's CSS file and get the same effect, which is a much stronger statement than it sounds, because the visual identity of that theme is carried largely by one stylesheet.
The third is the caveat: the port is not made for the latest Butterfly, and your index.css may therefore show bugs in this theme. The upstream theme moves quickly, and a port that tracks a moving stylesheet inherits the risk. Anyone upgrading the original theme's CSS should expect to check their overrides rather than assume they carry over.
The rest of the notes are about what the theme does for itself. Because a dynamic blog can implement features in the program, most of them no longer need a third party API, and the README notes these can be customised in the theme appearance settings. That is the theme's main philosophical difference from the Hexo original: what was once an external service call becomes a setting in the admin panel.
Features the theme handles without a third party service
The list of implemented features is long and specific, and reading it tells you what a Typecho blog owner actually wanted from a theme.
On the security and access side there is whole site encryption or a disable access switch, article encryption, a Google and hCaptcha human verification option for comments, and per article settings for replies to be visible only to those who reply.
On the reading side there is a reading mode, Pjax navigation, a table of contents that works on both desktop and phone, a card style design, two column layouts, secondary directory support, responsive layout, dark mode, and conversion between simplified and traditional Chinese.
On the everyday content side there is local search, which needs no external service, a built in 404 page, word count display, related articles, expired article reminders, and per article expiry settings, plus admin configuration of pinned posts, friend links with custom HTML, sidebar information, and the hiding or showing of sidebar items.
On the presentation side there is site wide colour configuration, Google or manual ad placement, Fancybox for large images, image lazy loading, Snackbar notifications, code blocks that show their language and can collapse, expand, copy and wrap, and a one-click option to apply custom modifications to the theme.
Two more are worth calling out because they are the kind of thing that breaks on cheap hosting. There is a live visitor counter, and the README notes that some virtual hosts seem unable to use it, and there is online editing of documents, which turns the theme into a small content management surface of its own.
The checklist that still has empty boxes
The most useful thing in the README is the list of things that are not done, because it is maintained in the same document as the list of things that are.
The unchecked items include several code colour schemes, darker, pale night, light, ocean, mac and mac light, with the ability to customise them, the option to disable text copying or to add a copyright notice when content is copied, Mathjax and KaTeX for maths rendering, several chat widgets such as Chatra, Tidio, Daovoice, Gitter and Crisp, the activate_power_mode typing effect, background effects such as static and dynamic ribbons and Canvas Nest, a built in preloader animation, a photo wall, and PWA support.
Two of those omissions matter more than the others for particular readers. A maths blog without Mathjax or KaTeX has to fall back on images or on the blog program's own handling, and a reader who wants to install the theme as a progressive web app will not get one.
The rest of the document points to a blog post with the details, and there is a section inviting help: report bugs and suggestions as issues, send a pull request if you can, and if you are only a user, star the repository to encourage the author to keep updating it. The project also asks for a drink, with donation codes for WeChat and Alipay.
The template layout, which is conventional Typecho
The top level of the repository is a Typecho theme layout, and knowing it makes the theme easier to extend.
The entry files are index.php for the front page, post.php for a single article, page.php for pages, archive.php for date and category archives, articles.php for the article list, category-list.php, tags.php, link.php for the friend links page, photos.php and photo-list.php for a photo section, and 404.php for the not found page.
index.php
post.php
functions.php
404.phpheader.php, footer.php and functions.php hold the shared template logic, and the includes directory holds the partials.
The static assets sit in css, js, img and public, with an index.css at the root that is the theme's own stylesheet, the one that the Hexo compatibility note is about. There is a config directory for theme configuration, an edit directory, an api directory, an OwO.json file, and an online.dat file that is presumably the state behind the online visitor count.
Two observations follow. First, there is no build step and no package manager manifest in the top level entries, so the theme is deployed as plain files, and any change you make is a change you maintain by hand. Second, the presence of api and edit directories suggests that some of the features, such as online editing and the visitor count, are implemented as endpoints in the theme rather than purely as templates, and that is worth checking before you deploy to a host with a restrictive PHP configuration.
The theme also ships a screenshot.png and a README with a project structure that matches what a Typecho theme needs, so porting modifications from an existing customisation is a matter of editing the same file names.
Maintenance, versions and who this is for
The picture that emerges is of a well-used theme maintained by one person, released as candidates, with the documentation living on the author's blog rather than in the repository.
The badges show a Typecho version of 1.2.0 and PHP 7.4 and above as the supported range, while the development environment section asks for Typecho 1.3.0 and PHP 8.2, which is a gap between what the theme claims to support and what it is developed against. If you are on a recent Typecho, the theme will run, but the combination the author tests is the one to trust.
The repository was last pushed on 2026-06-28 and has not been archived, with the most recent tags being the 1.9.0 release candidates from the same day and from May 2026, and the last stable release 1.8.1 from March 2025. There are no GitHub releases beyond those tags, and the releases page is where the documentation tells you to install from.
So who should use it. Someone who wants the Butterfly look on Typecho, who is comfortable running release candidates, and who reads the change notes. Someone who wants a theme with a feature checklist this detailed and a maintainer who clearly responds to issues is in good hands, and the dependency on a single author for updates is the same trade every free theme carries.
And who should not. Someone whose blog depends on maths rendering, a photo wall or offline installability, and someone who expects the port to track the upstream Butterfly theme release for release.
Editorial conclusion
Adopt Typecho-Butterfly if you want the look and behaviour of the Hexo Butterfly theme on a Typecho blog, especially if you already have Hexo posts in markdown that you want to bring over. Do not adopt it expecting parity with the latest upstream Butterfly release, because the port explicitly lags it and your own index.css can break as a result, and note that the unfinished items include maths rendering, a photo wall and PWA support. Before you install, download from the Releases page rather than the code tab, since the README warns that the code archive can be missing updates or ship them early, and check the version pair you get, since the current tags are release candidates rather than a stable release.
Frequently asked questions
What is Typecho-Butterfly?
It is a Typecho version of the Butterfly theme, originally built for Hexo. The author ported it because they switched devices often, found the Hexo workflow inconvenient and hit third party limits on some features, and the port is written in PHP and licensed under Apache-2.0.
How do I install the Typecho-Butterfly theme?
Download the archive from the Release page rather than the code page, because the README warns that the code archive can have missing or early updates that break the page, then extract it into the theme directory inside your Typecho blog installation.
Can I move my posts from Hexo to Typecho-Butterfly?
Yes. One of the stated porting features is that the transfer is easy because both systems store posts as markdown documents. Existing Butterfly users can also reuse the original theme's CSS file for the same visual effect.
Which features are not implemented in Typecho-Butterfly yet?
The checklist in the README leaves several items open: multiple code colour schemes, disabling text copy or adding a copyright notice, Mathjax and KaTeX, several chat widgets, typing and background effects, a preloader animation, a photo wall and PWA support.
What PHP and Typecho versions does Typecho-Butterfly support?
The badges state Typecho 1.2.0 and PHP 7.4 and above, while the documented development environment is Typecho 1.3.0 with PHP 8.2, PostgreSQL and NGINX. The author advises running and developing in the same environment for the best experience.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/wehaox-typecho-butterfly)Was this useful?