NexT for Hexo: what the theme does, how to install it, and where it stops

What NexT solves for a Hexo blog

Hexo ships with a default theme that is deliberately plain. Anyone who wants a finished blog look has to either write templates or pick a theme and live with its choices. NexT is the second option taken seriously: the README calls it "a high quality elegant Hexo theme" crafted from scratch, and the project ships four named schemes, Muse, Mist, Pisces and Gemini, each with a live preview on theme-next.js.org. Choosing between them is a one-line config change rather than a fork.

The audience is narrower than the download numbers on npm might suggest. NexT assumes you already run Hexo, that your content lives in Markdown, and that you are comfortable editing YAML. If your site is built on another generator, nothing here transfers. The theme's own repository requires Hexo 7.0.0 or later, which the README states with a badge, so an old Hexo install is a hard blocker rather than a soft warning.

The interesting part is not the visual design. It is the upgrade story. The README is explicit that modifying files inside the theme is not recommended because it causes merge conflicts and because modified files may be discarded when upgrading. That single sentence shapes everything else about how the project expects to be used.

How the theme is structured and how a page gets built

The repository layout is a standard Hexo theme shape: layout/ holds the templates, source/ holds CSS and JavaScript, languages/ holds translations, scripts/ holds the theme's own Hexo plugin code, and two YAML files at the root, _config.yml and _vendors.yml, carry the settings. The npm package publishes exactly those directories plus docs, so an npm install gives you the same tree as a git clone.

Configuration is split in two. _config.yml holds theme behaviour: which scheme is active, which plugins are on, and which CDN serves third-party assets. _vendors.yml holds the vendor asset definitions themselves. Because both files sit inside the theme directory, the project directs users to the Alternate Theme Config mechanism instead, which keeps your edits in a file outside the theme so that npm install hexo-theme-next@latest or git pull does not overwrite them. Custom layout and style changes go through Custom Files for the same reason.

Plugins are the second layer. The README describes them as extending and expanding functionality, with some features requiring third-party libraries or extra configuration. Each is a boolean or a value in the theme config. Enabling pjax, for example, is a single key set to true, and the theme then loads the pjax library from a CDN. The default CDN is CDNJS, with UNPKG and jsDelivr offered as alternatives through the vendors.plugins key. That design keeps the package small, but it also means most interactive features on your site depend on a third-party CDN being reachable from your readers' browsers.

Installing NexT and turning on pjax

The README gives two install paths. On Hexo 5.0 or later the npm route is the shortest, run from inside your Hexo site directory. It places the theme under node_modules and lets you upgrade with a version bump.

cd hexo-site
npm install hexo-theme-next

After that, open the Hexo config file at the root of your site and point the theme variable at next. The README shows exactly this key and value, and without it Hexo keeps rendering the default theme.

theme: next

If you prefer a checkout you can inspect, the second path clones the repository into themes/next. This is the variant to pick when you want to read the templates before committing to the theme.

cd hexo-site
git clone https://github.com/next-theme/hexo-theme-next themes/next

For a first real use, enable pjax. The README presents this as the example of how easy plugin configuration is: set the key to true in the theme config file, and the theme loads the pjax library, which the README describes as fast Ajax navigation. On a rebuild, page transitions stop doing full reloads. If pjax does not take effect, the first thing to check is whether your edit landed in the theme's own _config.yml rather than an alternate config file, because the alternate file is what survives an upgrade.

# Easily enable fast Ajax navigation on your website.
# For more information: https://github.com/next-theme/pjax
pjax: true

Switching CDN providers follows the same pattern. To move off CDNJS, set the plugins key under vendors to unpkg, which the README lists alongside jsDelivr as an optional provider.

vendors:
  plugins: unpkg

Editing the theme directly is the trap

The most common way to break a NexT install is also the most natural one: open a template in layout/, change it, and move on. The README warns that this causes errors such as merge conflicts and that the modified files may be discarded when upgrading. With the npm install path the failure is quiet. You run npm install hexo-theme-next@latest, the package directory is replaced, and your edits are gone. The site does not error. It simply reverts to the stock layout, and if you had wired content into a modified template, that content disappears from the rendered output.

The git clone path behaves differently but not better. A git pull on a branch you have committed to can conflict, and resolving that conflict is manual work every time you update. Neither path protects local edits, which is why the project pushes the alternate config and custom files routes so hard.

There is a second boundary worth naming. NexT is a presentation layer. It does not manage content, search indexing, comment storage or analytics on its own. Those arrive through plugins, and many plugins are third-party libraries pulled from a CDN. If your readers are behind a network that blocks CDNJS, UNPKG or jsDelivr, the features you enabled will not load, and the theme's own files will not tell you why. Self-hosting those assets is possible in principle, but the README does not document that path, so you would be working against the grain of the project's design.

NexT against a from-scratch Hexo theme

The real alternative is not another named theme. It is writing your own Hexo theme, or starting from the bare default and adding only the templates you need. That approach gives you total control over markup, no CDN dependency, no upgrade treadmill and no config file to reconcile. It also means you build pagination, archives, tag pages, table of contents, code highlighting and dark mode yourself, and you maintain them.

NexT's trade is the opposite: you accept its markup, its four schemes and its config surface, and in exchange you get a project that publishes releases, documents its upgrade path and ships translations through Crowdin and languages/ rather than leaving internationalisation to you. The repository shows a test directory, a linter config and CI workflows for linting and testing, so changes to the theme are checked before release. A personal theme has none of that.

A useful way to decide: if your blog's value is the writing and the theme is infrastructure, NexT is the lower-effort choice. If the site's visual identity is the point, or if you need markup that no existing theme produces, the from-scratch route costs less over time than fighting a theme's structure.

Upgrades, licence and what maintenance actually looks like

Updating NexT is two commands, one per install path. The npm route installs the latest published version; the git route pulls the master branch. The README asks you to read the release notes before updating, and that is not boilerplate, because the theme has changed enough between major lines that the project maintains a separate upgrade guide for moving from v5.x or v7.x to the current version.

The repository was last pushed on 2026-09-18, and the most recent release listed is v8.29.0 from 2026-08-05, with v8.28.0 before it on 2026-07-01 and v8.27.0 on 2026-01-07. The cadence is uneven, with a six-month gap between the January and July releases, so pinning a version and updating deliberately is more realistic than tracking every tag.

On licensing, the package.json declares AGPL-3.0-only and the README badge says AGPL. That is a copyleft licence, and it is a stronger obligation than the MIT licence many Hexo themes use. If you redistribute a modified theme, or run a modified version as a network service, the AGPL's terms are likely to apply to your changes. This is not legal advice and I am not a lawyer; if your use is commercial or you plan to redistribute, read LICENSE.md and get proper advice before you build on it.

Editorial conclusion

Adopt NexT if you run Hexo 7.0.0 or later, want a maintained theme with release notes and an upgrade path, and are willing to configure it through an alternate config file rather than editing theme files. Do not adopt it if you want to rewrite the layout directly inside the theme or if you cannot accept AGPL-3.0-only terms. Before installing, check your Hexo version against the required >=7.0.0, confirm you can add a theme config file outside the theme directory, and read the release notes for the version you plan to install.

Frequently asked questions

Official sources

1. Issues
2. next-theme/hexo-theme-next on GitHub
3. Project website
4. README
5. Releases