{"id":11033,"library":"hexo","title":"Hexo Static Site Generator","description":"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.","status":"active","version":"8.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/hexojs/hexo","tags":["javascript","website","blog","cms","framework","hexo","typescript"],"install":[{"cmd":"npm install hexo","lang":"bash","label":"npm"},{"cmd":"yarn add hexo","lang":"bash","label":"yarn"},{"cmd":"pnpm add hexo","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const Hexo = require('hexo');","symbol":"Hexo","correct":"import { Hexo } from 'hexo';"},{"note":"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.","wrong":"import { HexoConfig } from 'hexo';","symbol":"HexoConfig","correct":"import type { HexoConfig } from 'hexo';"},{"note":"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.","symbol":"Hexo CLI","correct":"npm install hexo-cli -g"}],"quickstart":{"code":"npm install hexo-cli -g\nhexo init my-blog\ncd my-blog\nnpm install # Install dependencies for the new blog\nhexo new \"My First Post\"\nhexo generate\nhexo server","lang":"bash","description":"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."},"warnings":[{"fix":"Upgrade your Node.js environment to version 20.19.0 or newer before upgrading Hexo to v8.x.","message":"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.","severity":"breaking","affected_versions":">=8.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=7.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install the compatibility plugin: `npm install hexo-tag-embed --save`","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.","error":"Error: Cannot find module 'hexo-tag-embed'"},{"fix":"Update your Node.js environment to version 20.19.0 or higher.","cause":"Running Hexo v8.0.0 or newer with an unsupported Node.js version (e.g., Node.js 16 or 18).","error":"Error: Node.js version x.y.z is not supported. Please upgrade Node.js to >=20.19.0."},{"fix":"Either stop the conflicting process or start Hexo server on a different port: `hexo server --port 5000`","cause":"Another process is already using the default port (4000) or the port specified for `hexo server`.","error":"Port XXXXX is already in use, start another Hexo instance with --port YYYYY"}],"ecosystem":"npm"}