Hexo Static Site Generator

8.1.1 · active · verified Sun Apr 19

Hexo is a fast, simple, and powerful blog framework for Node.js, designed for generating static websites. The current stable version is 8.1.1, with minor and patch releases occurring frequently, typically every few weeks to months, and major versions bringing significant changes roughly annually. It features blazing-fast content generation, robust support for GitHub Flavored Markdown, and compatibility with most Octopress plugins. Key differentiators include its one-command deployment capabilities to platforms like GitHub Pages and Heroku, a highly extensible API for plugin development, and a rich ecosystem boasting hundreds of themes and plugins. Hexo primarily targets developers and bloggers who prefer a static site approach with a command-line interface.

Common errors

```
Error: Cannot find module 'hexo-tag-embed'
```
cause Upgrading to Hexo v7.0.0 or later without installing the `hexo-tag-embed` plugin, while still using old embed tags like `gist`, `youtube`, etc., in your posts.

fix Install the compatibility plugin: `npm install hexo-tag-embed --save`
```
Error: Node.js version x.y.z is not supported. Please upgrade Node.js to >=20.19.0.
```
cause Running Hexo v8.0.0 or newer with an unsupported Node.js version (e.g., Node.js 16 or 18).

fix Update your Node.js environment to version 20.19.0 or higher.
```
Port XXXXX is already in use, start another Hexo instance with --port YYYYY
```
cause Another process is already using the default port (4000) or the port specified for `hexo server`.

fix Either stop the conflicting process or start Hexo server on a different port: `hexo server --port 5000`

Warnings

breaking Hexo v8.0.0 dropped support for Node.js 16 and Node.js 18. This means users upgrading to v8.0.0 or later must be running Node.js 20.19.0 or higher.
Fix: Upgrade your Node.js environment to version 20.19.0 or newer before upgrading Hexo to v8.x.
breaking In Hexo v7.0.0, several built-in tags (such as `gist`, `youtube`, `jsfiddle`, and `vimeo`) were removed from the core. Using these tags in existing posts after upgrading will result in errors or broken content.
Fix: Install the `hexo-tag-embed` package (`npm i hexo-tag-embed`) in your Hexo project to re-enable support for these legacy embed tags.
gotcha When developing plugins or themes, changes often require restarting the `hexo server` process to reflect updates, especially for generators, filters, and new helpers. Incremental rebuilds only apply to content changes by default.
Fix: After making changes to theme files, helper functions, or plugin logic, stop the `hexo server` process (Ctrl+C) and restart it (`hexo server`) to ensure all changes are loaded.

Install

npm install hexo npm
yarn add hexo yarn
pnpm add hexo pnpm

Imports

Hexo
wrong:
```
const Hexo = require('hexo');
```
correct:
```
import { Hexo } from 'hexo';
```
While Hexo ships TypeScript types, it is fundamentally a CommonJS module. Direct ESM imports (`import { Hexo } from 'hexo'`) work in environments supporting CJS-to-ESM interop, but `require('hexo')` is often more reliable for programmatic usage within a Node.js CJS project. For TypeScript projects, `import Hexo from 'hexo';` might also be tried for default export behavior.
HexoConfig
wrong:
```
import { HexoConfig } from 'hexo';
```
correct:
```
import type { HexoConfig } from 'hexo';
```
Used for type-checking Hexo's configuration object. This is a type-only import and should be prefixed with `type` in TypeScript versions 3.8+ to avoid bundling issues.
Hexo CLI
```
npm install hexo-cli -g
```
Hexo is primarily used via its command-line interface. The `hexo-cli` package is typically installed globally to provide the `hexo` command for project initialization and management, rather than importing directly into application code for most users.

Quickstart

This sequence of commands installs the Hexo CLI globally, initializes a new Hexo blog in 'my-blog' directory, creates a new post, generates the static files, and starts a local development server.

npm install hexo-cli -g
hexo init my-blog
cd my-blog
npm install # Install dependencies for the new blog
hexo new "My First Post"
hexo generate
hexo server

view raw JSON →