hexo-theme-keep: A Lightweight Hexo Theme for Writing

Why hexo-theme-keep targets Hexo writers

hexo-theme-keep addresses a narrow problem: giving a Hexo site a writing-oriented presentation without introducing a broad collection of content and layout features. The project description calls it simple and light, and the README explicitly connects the theme with writing focus. Its audience is therefore not limited to developers building a general-purpose publishing platform. It is aimed at people who already use Hexo and want the theme layer to stay out of the way.

The project is a Hexo theme rather than a standalone static site generator. That distinction matters because the theme does not replace Hexo. The README lists Node.js 14.0.0 or later and Hexo 5.0 or later as requirements through its compatibility badges. The repository includes layout, source, languages, docs, scripts, and a root _config.yml, which reflects the expected structure of a theme packaged for a Hexo site.

Keep also presents separate documentation links for configuration and advanced usage, including language settings. This indicates that customization exists beyond the initial installation. However, the README does not enumerate a large plugin system, administration panel, or content modeling layer. The value proposition is based on the theme's presentation and setup model rather than a documented service platform.

How Keep fits into a Hexo site

Keep is installed into a Hexo project's theme directory, or installed as the hexo-theme-keep package and selected through the site's Hexo configuration. The repository layout shows the likely division of responsibilities: layout contains theme templates, source contains frontend assets such as JavaScript and CSS, languages contains localization files, and _config.yml contains the theme configuration entry point. The package scripts also refer to source/js and source/css, confirming that the theme includes authored frontend code and styles rather than only documentation.

The README does not provide a complete rendering diagram or list every template and variable. Based on the repository structure, Hexo supplies the site and its generated content, while Keep supplies the theme templates and assets used to present that content. Selecting `keep` in the Hexo configuration tells Hexo which theme to use. The language directory suggests that interface text can be localized, while the documentation links point to separate configuration pages for site-specific settings.

This design makes Keep appropriate for sites whose publishing workflow is already handled by Hexo. It is not a CMS, a writing editor, or a deployment service. A reader should not expect the theme itself to solve content versioning, comment hosting, analytics, search indexing, or image processing. Those concerns would need to come from Hexo configuration, generated content, external services, or other integrations, none of which are specified as built-in Keep features in the README.

Installing Keep and creating a first Hexo site theme selection

The README documents two installation methods. For Hexo 5.0 or later, npm is the simpler documented route. The command installs the theme package in the Hexo project directory.

cd your-hexo
npm install hexo-theme-keep

The repository also documents a Git-based installation. This copies the theme into the `themes/keep` directory with a shallow clone.

cd your-hexo
git clone https://github.com/XPoet/hexo-theme-keep --depth=1 themes/keep

After either method, the Hexo configuration must select the theme by setting the `theme` variable.

theme: keep

The README does not include a separate command for generating the first site or running a preview server, so this article does not invent one. A first real use begins with an existing Hexo site whose content has already been created, then applying the theme setting and using the site's normal Hexo workflow. The documentation provides an online demo at `https://keep.xpoet.cn/`, which can be used to inspect the theme's intended presentation before local changes.

Updating Keep without accumulating theme changes

Keep publishes versions, including `v4.3.0` on 2026-06-11. The README says the recommended npm update path installs the latest published package.

cd your-hexo
npm install hexo-theme-keep@latest

For a Git checkout, the documented alternative is to enter the theme directory and pull changes.

cd themes/keep
git pull

The README directly warns against modifying files inside the Keep theme. Its stated reason is that local modifications can cause errors, including merge conflicts, and may be discarded during an upgrade. That warning has architectural significance. A site that needs persistent customization should distinguish between theme configuration and direct edits to `layout`, `source`, or other theme internals. The documentation does not specify the complete set of supported override points, so it would be unsafe to promise that every desired customization has a stable extension mechanism.

The repository includes formatting and linting scripts, but those are development commands rather than documented commands for site operators. The package defines `format`, `lint:style`, and `prepare` scripts for contributors and local development. They should not be treated as required deployment steps for using Keep.

The AGPL-3.0 license and maintenance boundary

The project is licensed under AGPL-3.0. That designation matters when a site distributes a modified version of the theme, offers it over a network, or incorporates theme code into a broader service. The README identifies the license, and the repository contains a LICENSE file, but this review does not provide legal interpretation or claim that any particular deployment satisfies the license terms.

Keep is not archived. The last push was on 2026-06-11, and the repository includes recent release information for `v4.3.0`, while earlier releases include `v4.2.5` from 2024-11-25 and `v4.2.4` from 2024-11-21. This establishes recent project activity, but it does not guarantee compatibility with every Hexo configuration or third-party extension. Upgrade work is made more predictable by the README's warning against direct theme edits.

The package metadata identifies Node.js and Hexo compatibility through project badges, while `package.json` contains development dependencies for Prettier, Stylelint, Stylus, Husky, lint-staged, and commit tooling. The runtime dependency set is not described in that file. That omission means an engineer should inspect the installed package and generated site before assuming that a particular integration is bundled.

Where Keep is the wrong choice

Keep is a poor fit when the defining requirement is a feature-heavy publishing system rather than a focused Hexo presentation. The README does not document built-in capabilities for user accounts, subscription management, payments, comments, advanced search, or a visual administration workflow. If any of those are required, they would need to be supplied elsewhere, and the compatibility of those additions with Keep is not established here.

It is also a poor fit for teams that expect to edit the theme's internal files freely. The documented update process treats theme files as upstream-owned material. Local edits can create merge conflicts during `git pull`, and package updates can discard modified files according to the README. A team that needs a bespoke layout should first determine whether its changes can be represented through supported theme configuration. The documentation does not prove that all customization can be kept outside the theme directory.

The stated Node.js and Hexo minimums create another boundary. A project using an older Hexo or Node.js environment would need to resolve compatibility before installing Keep. No compatibility matrix is provided beyond the badges and README statements.

Keep compared with a custom Hexo theme

A real alternative is to maintain a custom Hexo theme in the site's `themes` directory. Keep supplies a packaged theme intended for installation and periodic updates. A custom theme instead puts the site's templates, styles, and frontend code under the site's own control. That difference is more useful than a generic comparison based on appearance.

Keep offers a lower initial setup cost for a writer who accepts its existing presentation and upgrade discipline. The package can be installed with npm, selected with one Hexo configuration value, and updated with a package command. A custom theme requires the engineer to design, maintain, and test the templates and assets, but it also gives direct control over internal changes. Keep's Git clone option sits between the package and the fully custom case because it exposes the repository directly, yet the README still warns against modifying its files.

Neither alternative inherently solves the parts outside theme rendering. Hexo still handles site generation and deployment. Keep reduces the amount of theme work, while a custom theme increases it in exchange for control. The correct choice depends on whether the priority is a maintained theme boundary or ownership of every template detail.

Editorial conclusion

Adopt hexo-theme-keep if you are building a personal Hexo site and prefer a focused theme with a small conceptual surface. Do not choose it if you need undocumented integrations or expect freedom to modify theme files without upgrade consequences. Before adoption, verify Hexo 5.0 or later, the AGPL-3.0 license implications, and whether the documented configuration matches the site features you require.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. XPoet/hexo-theme-keep on GitHub