Hexo Introduction

What is Hexo

Hexo is a fast, simple and powerful static blog framework powered by Node.js. You only need to write in Markdown, and Hexo generates pure static HTML pages in seconds — no database, no PHP or other backend environment required. Any static hosting (GitHub Pages, Vercel, Nginx, object storage, etc.) can serve it directly.

Compared with dynamic blog systems, Hexo’s advantages:

Fast: static pages, no server-side rendering, CDN-friendly
Simple: write in Markdown, version with Git, deploy with one command
Powerful: a huge ecosystem of plugins and themes (this tutorial is based on the deeply customized matery theme)
Secure: no database, no runtime attack surface, naturally resistant to attacks

This blog (夜法之书) is built on Hexo 8.1.2 + matery theme, hosted in production by Vercel.

Environment Requirements

Component	Version	Notes
Node.js	>= 20	Hexo 8.x runtime (this site uses the LTS version; package.json declares no engines field — Node >= 20 is the actual runtime requirement)
npm	bundled with Node (project locks npm@9)	Installed with Node.js, used to install Hexo and plugins
Git	any modern version	Clone themes, deploy to Git hosting platforms

Verify the environment:

node -v    # something like v20.x
npm -v     # 9.x (project packageManager locks to npm@9)

Common Commands

Command	Purpose
`hexo init [folder]`	Create a new site. Equivalent to cloning hexo-starter and installing dependencies
`hexo new post <title>`	Create a post in `source/_posts/` (quote the title if it contains spaces)
`hexo new page <name>`	Create a standalone page (e.g. about, tags)
`hexo new draft <title>`	Create a draft in `source/_drafts/`
`hexo publish <title>`	Publish a draft as a regular post
`hexo generate`	Generate static files to `public/` (`-w` watch for changes, `-d` deploy after generating)
`hexo server`	Start a local preview server, default `http://localhost:4000/` (`-p` to set the port)
`hexo deploy`	Deploy the site (push to the configured Git repo, `-g` generates before deploying)
`hexo clean`	Clear the cache (`db.json`) and the generated directory (`public`); recommended after changing config/plugins
`hexo --safe`	Safe mode: skip plugins and scripts; use when debugging plugin conflicts
`hexo server --draft`	Show drafts in preview
`hexo version`	Show the Hexo version

Common combinations (npm scripts in this project’s package.json):

npm run build    # hexo generate (also builds the pagefind search index)
npm run clean    # hexo clean
npm run server   # hexo server
npm run deploy   # hexo deploy

Workflow

Write (Markdown) → Generate (hexo generate) → Deploy (hexo deploy)

Write: hexo new post "Post title" creates a post; edit the file under source/_posts/ in Markdown
Preview: hexo server checks the result locally (default localhost:4000)
Generate: hexo generate renders posts into static files under public/
Deploy: hexo deploy pushes to a Git repo; or push to GitHub and let platforms like Vercel build automatically

Tip: after modifying _config.yml or theme config, always run hexo clean before hexo generate, otherwise the cache may cause changes not to take effect.

Next Steps

Installation & Theme Setup: build a site with the matery theme
Directory Structure & Content Management: understand file layout and front-matter