hexo-theme-icarus: A Hexo Theme With Per-Page Widget Configuration

The problem Icarus solves for a Hexo blog

Hexo ships a default theme that is deliberately plain. Replacing it usually means either writing layouts from scratch or adopting a theme whose configuration is a single global file. Icarus targets the second path but breaks the single-file assumption: the README states that the theme "allows you to configure your site on a per-page or per-layout basis." That is the distinguishing claim. A documentation page, a landing page and a blog post can each carry a different widget arrangement without forking the theme or duplicating layouts.

The audience is therefore narrower than "everyone using Hexo." It suits people who already run Hexo, are comfortable editing YAML, and want comment, search, sharing and analytics integrations available as configuration rather than as separately installed Hexo plugins. The README lists those integrations as built in: Changyan, Disqus, DisqusJS, Facebook, Gitalk, Gitment, Isso, LiveRe, Utterance and Valine for comments; Algolia, Baidu, Google CSE and Insight for search; AddThis, AddToAny, Baidu Share, Share.js and ShareThis for sharing. If you want a theme you never touch after install, the configuration surface here is larger than you need.

How the configuration inheritance actually works

The mechanism visible in the README is a three-level override chain. The site-level `_config.yml` sets defaults. A post's front matter can override them. A `_config.page.yml` file can override them for a whole layout. The README's example uses the `widgets` key at all three levels: the site config places a `profile` widget on the left and `recent_posts` on the right, the post front matter moves `recent_posts` to the left, and the page config sets `widgets: null` to remove them entirely.

That last value is the interesting one. Setting a key to null is how you suppress an inherited list, which means the merge is not a naive deep merge of everything. The dependency list includes `deepmerge`, so merging is part of the build, but the documented behavior of `widgets: null` shows the theme treats an explicit null as a deliberate erasure rather than as an absent value.

The rendering stack is Inferno.js with `hexo-renderer-inferno`, styled through Stylus with `bulma-stylus`, and paginated with `hexo-pagination`. The repository layout reflects this: `layout/` holds the templates, `source/` the assets, `scripts/` the Hexo-side logic, and `languages/` the translation files that the README invites contributions to. Code highlighting is not implemented in the theme itself; the README says Icarus imports stylesheets directly from the highlight.js package and exposes more than 90 highlight themes.

Installing hexo-theme-icarus and setting your first widget layout

The README gives a two-command install. The first installs the theme from npm; the second points Hexo's `theme` setting at it. Both are run from the root of an existing Hexo site.

$ npm install hexo-theme-icarus
$ hexo config theme icarus

After that, the README directs you to the "Getting Started with Icarus" page in the documentation for the remaining setup. The npm package declares `"engines": { "node": ">=14" }`, so check `node --version` before starting; an older runtime is outside what the package declares support for.

The first real configuration step is the widget list in `_config.yml`. The README shows this shape, with a `type` and a `position` for each entry:

widgets:
  - type: profile
    position: left
  - type: recent_posts
    position: right

With that in place, a rebuild should place a profile card on the left column and a recent-posts list on the right. To change the arrangement for one post only, put the same key in that post's front matter and swap the positions:

widgets:
  - type: profile
    position: left
  - type: recent_posts
    position: left

To remove widgets from a layout entirely, the README's page-level example sets `widgets: null` in `_config.page.yml`. The README does not document what happens when a widget `type` is misspelled, so treat an unrecognized type as untested territory and check the rendered output after each change.

Where Icarus gets in your way

The dependency list is the first constraint. `package.json` requires `hexo ^7.1.1`, `inferno ^8.2.3` and Node 14 or newer. A site still on Hexo 6 is outside the declared range, and the README offers no migration path for that case. Because the theme pulls in `hexo-renderer-inferno` and `hexo-renderer-stylus` as dependencies, it also participates in your renderer chain; if you already use a different renderer for the same file types, that is a conflict the README does not address.

The release history is a second consideration. The most recent release listed is 6.1.1 from 2024-12-14, following 6.1.0 in June 2024 and 6.0.0 in February 2024. The repository's last push was on 2026-04-27, so work continues between releases, but a reader should expect a theme whose tagged versions move slowly. If your project needs a fix that landed after 6.1.1, installing from the npm registry will not give it to you.

There is also a documentation asymmetry. The README enumerates plugin names across comments, search, sharing, donation, widgets and analytics, but the configuration keys for those plugins live in the documentation site rather than in the repository README. Anyone evaluating Icarus from the README alone will know which services are supported without knowing how to enable them.

Icarus compared with NexT and other Hexo themes

NexT is the obvious alternative and appears in the related searches for this project. The difference is in the configuration model rather than the feature list. NexT's configuration is organized around a single theme config file with a large set of switches, and its documentation is built around that file. Icarus splits the same kind of settings across site config, post front matter and per-layout files, which is more work to reason about but lets one post differ from the rest of the site without a separate layout.

The rendering stack differs too. Icarus is built on Inferno.js, Stylus and Bulma, per the README's development section. A theme built on a component renderer will produce different markup and a different theming workflow from one built on plain EJS or Pug templates, and the practical consequence is that overriding a template means working with the theme's component structure, not just editing an HTML fragment.

If your priority is a theme whose documentation answers every configuration question in one place, NexT's single-file model is easier to hold in your head. If your priority is varying layout per post or per page without duplicating templates, Icarus's inheritance chain is the reason to pick it.

Licence and upgrade cost

Icarus is MIT licensed, and `package.json` carries `"license": "MIT"` alongside the LICENSE file at the repository root. For a theme, that is permissive in the practical sense: you can modify the layouts and ship the result with your site. The MIT terms do not, by themselves, settle the licensing of the third-party plugins the theme can be configured to load. Enabling Disqus, Gitalk, Valine or a Google analytics plugin means your pages call services governed by those providers' own terms, and the README does not discuss that. That is a question for whoever owns your site's compliance, not something a theme's licence answers.

Upgrade cost is mostly the Hexo version floor. Because the package depends on `hexo ^7.1.1`, moving to a new Icarus release can require moving Hexo first, and the theme's own renderer dependencies come along with it. There is no changelog in the repository README, so the release notes on the releases page are the place to check before upgrading. Pinning the theme version in your site's `package.json` and upgrading deliberately is cheaper than tracking the npm latest tag.

Editorial conclusion

Adopt Icarus if you run Hexo 7 and want per-post control over widgets and built-in search, comment and analytics plugins without writing your own layouts. Skip it if you are pinned to an older Hexo or Node below 14, since package.json declares node >=14 and hexo ^7.1.1. Before committing, verify that your Hexo version satisfies that range and that the plugin you need appears in the documentation categories, because the README lists plugin names but not their config keys.

Frequently asked questions

Official sources

1. License: MIT
2. ppoffice/hexo-theme-icarus on GitHub
3. Project website
4. README
5. Releases