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

> Icarus is an MIT-licensed Hexo theme built on Inferno.js, Stylus and Bulma. Its config inheritance model and plugin roster are its real selling points; the Node version floor and the release cadence are the trade-offs.

**ppoffice/hexo-theme-icarus** — A simple, delicate, and modern theme for the static site generator Hexo.

- Repository: https://github.com/ppoffice/hexo-theme-icarus
- Website: https://ppoffice.github.io/hexo-theme-icarus/
- Stars: 6,649 · Forks: 1,522
- Language: JavaScript
- License: MIT
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/ppoffice-hexo-theme-icarus

## 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.

```bash
$ 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:

```yaml
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:

```yaml
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.

## 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.

## FAQ

### What is hexo-theme-icarus?

It is a theme for the Hexo static site generator, described in its README as "a simple, delicate, and modern theme." It is distributed on npm as hexo-theme-icarus and licensed under MIT.

### How do I install hexo-theme-icarus?

The README gives two commands: run npm install hexo-theme-icarus in your Hexo site, then run hexo config theme icarus. It then points to the Getting Started with Icarus documentation page for the rest of the setup.

### Can hexo-theme-icarus use a different widget layout on one post?

Yes. The README shows the widgets key set in the site _config.yml and then overridden in a post's front matter, and a per-layout _config.page.yml can set widgets to null to remove the widget columns for that layout.

### Which Node and Hexo versions does hexo-theme-icarus require?

The package.json in the repository declares node >=14 and depends on hexo ^7.1.1. Sites below those versions are outside the declared range.

## Sources

- [License: MIT](https://github.com/ppoffice/hexo-theme-icarus/blob/master/LICENSE)
- [ppoffice/hexo-theme-icarus on GitHub](https://github.com/ppoffice/hexo-theme-icarus)
- [Project website](https://ppoffice.github.io/hexo-theme-icarus/)
- [README](https://github.com/ppoffice/hexo-theme-icarus/blob/master/README.md)
- [Releases](https://github.com/ppoffice/hexo-theme-icarus/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ppoffice-hexo-theme-icarus