Hexo Theme Fluid: a Material Design theme installed through npm

What Fluid solves for a Hexo blog owner

Hexo generates a static site, but it ships no visual design. Every blog owner either writes Nunjucks or EJS templates against Hexo's layout API or picks a theme. Fluid is the second option: a theme package that supplies layouts, styles, scripts and a configuration file, so the blog owner edits YAML instead of templates.

The audience is narrow and specific. You need an existing Hexo site, Node at 10.13.0 or newer, and Hexo at 5.0 or newer, which is what the README's badges state. If you are choosing a static site generator from scratch, Fluid is not part of that decision; it is a downstream choice made after Hexo is already in place.

What the theme adds beyond styling is a set of built-in features that would otherwise each be a separate plugin: comment integrations, page view statistics, local article search, dark mode, footnotes, LaTeX math and mermaid diagrams. The README lists all of these as checked items. Bundling them means fewer packages to install and fewer version conflicts to resolve, at the cost of configuring them through the theme's own keys rather than through the plugins' own documentation.

How the theme is structured and where configuration lives

The repository layout is a conventional Hexo theme: layout/ holds the templates, source/ holds the assets, languages/ holds the translation files, scripts/ holds Hexo extension scripts, and _config.yml is the theme's default configuration. The package.json files array publishes exactly those five entries plus the config, so the npm package contains the theme and nothing else.

Configuration is layered. The theme ships _config.yml, but the README instructs you to create _config.fluid.yml in the blog directory and copy the theme's _config.yml contents into it. That blog-level file is the one you edit. This matters at upgrade time: when a new theme version adds or renames a key, your copy does not change automatically, and you are the one who reconciles it. The README does not document a merge or migration command for that step.

There is one structural quirk worth knowing before you file an issue. package.json declares "main": "package.json", which is not a JavaScript entry point. It is harmless for a Hexo theme, since Hexo loads themes through its own directory conventions rather than through Node's module resolution, but it means the package cannot be required as a library. The peerDependencies field lists nunjucks at ^3.0.0, which reflects the templating engine the layouts are written in.

The about page is not generated automatically. The README states that first-time users must create it manually, because it needs a layout attribute that a normal page does not carry.

Installing Hexo Theme Fluid and creating the about page

The README gives two installation routes. The npm route is recommended for Hexo 5.0.0 and above: run this inside the blog directory, and npm will add the theme to your dependencies.

npm install --save hexo-theme-fluid

After that, create _config.fluid.yml in the blog directory and paste in the contents of the theme's _config.yml. This file is what you edit from then on; the theme's own copy is the upstream default.

The alternative, for older setups or if you prefer not to use npm, is to download the latest release archive, extract it into the themes directory and rename the extracted folder to fluid. The folder name has to be exactly fluid, because the next step refers to it by that name.

Whichever route you took, point Hexo at the theme by editing _config.yml in the blog root. The theme key must match the folder name, and the language key controls the language the theme renders in.

theme: fluid  # 指定主题

language: zh-CN  # 指定语言，会影响主题显示的语言，按需修改

The about page needs one command and one front-matter edit. Run the page generator, then open the generated file and add the layout attribute.

hexo new page about

The README shows the resulting /source/about/index.md with title and layout in its front matter, layout set to about, followed by the page body in Markdown or HTML. Without that layout value the page will not use the about template.

The configuration file you now own

Copying the theme's _config.yml into _config.fluid.yml is a design decision with consequences, and the README presents it as a plain step rather than a trade-off. The benefit is that your settings survive a theme update, since npm overwrites the package's own _config.yml but not your blog-level file. The cost is that the two files drift. A key added in v1.9.9 will exist upstream and not in your copy, and the theme will fall back to a default you have not seen.

There is no documented mechanism in the README for detecting that drift. The README's update section is a single link to the documentation site rather than inline instructions, so the reconciliation procedure is not visible from the repository README alone. If you run this theme, treat the upgrade as a diff between the new upstream _config.yml and your copy rather than as a package install.

The same layering applies to page and post configuration. The README links to Hexo's front-matter documentation for article-level settings, which means per-post behaviour such as layout overrides is handled by Hexo's own conventions, not by Fluid-specific keys. That keeps the theme's surface smaller, but it also means debugging a rendering problem requires knowing which layer decided the outcome.

Where Fluid is the wrong choice

The clearest limitation is that Fluid is not a static site generator. It has no build pipeline of its own, no content model and no deploy story. Everything about generating and publishing the site comes from Hexo. If you are evaluating generators rather than themes, this project does not compete in that space at all.

The second limitation is release cadence. The recent releases are v1.9.7 on 2023-12-16, v1.9.8 on 2024-07-24 and v1.9.9 on 2026-03-10. The gap between v1.9.8 and v1.9.9 is roughly twenty months. The repository's last push was on 2026-06-24, so work continues between releases, but anyone expecting a steady stream of tagged versions will not find one. Plan upgrades around the tags you can actually see rather than around an assumed schedule.

The third is licensing. The project is GPL-3.0, and package.json records it as GPL-V3. That is a copyleft licence, which is a different proposition from the permissive licences many themes use. For a personal blog this rarely matters. For a theme you intend to modify and redistribute inside a commercial product, it is a question for your own legal review, not something this article can settle.

Finally, the built-in feature list is a form of coupling. Comment systems, statistics and search are configured through the theme rather than through the upstream plugins. If a service you use is not among the built-in integrations, the theme's configuration does not help you, and you are back to writing templates.

How Fluid differs from NexT, Butterfly and the rest

The comparison that matters is against the other Hexo themes people search for: NexT, Butterfly, Keep, Matery, Archer, Shoka and Redefine. They all occupy the same slot in the stack, so the differences are in configuration model, visual language and how the theme is distributed.

Fluid's distinguishing choice is the blog-level _config.fluid.yml. NexT, for comparison, is commonly configured through a theme config file inside the theme directory or through Hexo's alternate theme config mechanism, and its documentation is organized around a long options reference. The practical difference is upgrade behaviour: Fluid's approach protects your settings from being overwritten by npm, at the price of manual reconciliation when upstream keys change. A theme that keeps configuration inside the theme directory has the opposite trade-off, where upgrades can overwrite edits.

The visual difference is stated in the project's own description: Material Design. If you want that specific language, with its elevation, cards and typography, Fluid is the direct match. Themes like Shoka or Redefine take different visual directions, and picking between them is a design decision rather than a technical one.

Distribution is the other axis. Fluid publishes to npm as hexo-theme-fluid and its package.json files array is scoped to the theme directories. A theme distributed only as a GitHub release archive requires the download-and-rename route the README describes as method two. The npm route is what makes version pinning possible in a package.json, which is the practical reason to prefer it.

Maintenance, upgrades and what the licence means in practice

The repository is not archived and the last push was on 2026-06-24, so the project is being worked on. That is a statement about commits, not about release frequency, and the two diverge here: the most recent tag is v1.9.9 from 2026-03-10, preceded by v1.9.8 in July 2024. If your upgrade policy is tied to tagged releases, expect long intervals.

The upgrade procedure itself is documented on the official docs site rather than in the README, which links to it under an update heading. Because your settings live in _config.fluid.yml, an upgrade is two operations: install the new package version, then compare the new upstream _config.yml against your copy and port over anything that changed. The README does not describe a rollback path, so keeping your blog directory under version control is the only recovery mechanism the documentation supports.

On licensing: GPL-3.0 is a copyleft licence. The repository contains a LICENSE file and package.json declares GPL-V3. Themes are often assumed to be permissive, so this is worth checking against your own distribution plans before you build on it. Nothing here is legal advice; read the LICENSE file and decide with someone qualified if you plan to redistribute modified versions.

One more cost that is easy to miss: the theme's feature list is broad, and each built-in integration is a configuration surface you now maintain. A blog that uses none of the comment, statistics, search or math features still carries their configuration keys in the file you copied.

Editorial conclusion

Adopt Hexo Theme Fluid if you already have a Hexo site and want a Material Design front end without writing Nunjucks templates, and you are willing to copy the theme's _config.yml into a blog-level _config.fluid.yml and keep the two in step. Do not adopt it if you are not running Hexo, or if you need a theme whose release cadence tracks your Hexo version closely: v1.9.8 landed on 2024-07-24 and v1.9.9 on 2026-03-10. Before committing, verify that your Hexo version is at least 5.0 and your Node version at least 10.13.0, check that the npm route suits your update workflow, and read the update section of the official docs because the README only links to it.

Frequently asked questions

Official sources

1. fluid-dev/hexo-theme-fluid on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases