Building a Blog with Hexo

Updated 2026-03-04
#hexo #static-site #guide #nodejs

Hexo is a fast, Node.js-powered static site generator with a rich plugin ecosystem. In about ten minutes you can have a fully functional blog with RSS, search, sitemap, and multiple theme options — all served as static HTML with no server-side runtime.

Why Hexo

The static site generator landscape is crowded — Jekyll, Hugo, Eleventy, Astro, and many others. Hexo’s strengths are:

  • Node.js native — no Ruby or Go installation required if you’re already a JS developer
  • EJS/Nunjucks/Pug templating — familiar for front-end developers
  • Hexo CLI — a hexo new "Post Title" command scaffolds a new post instantly
  • Plugin ecosystem — search, feeds, sitemaps, and more, all as npm packages
  • Fast enough — a few hundred posts generate in seconds

Setup

Prerequisites

You need Node.js 16+ and npm (or yarn/pnpm). Verify with:

1
2
node --version  # v20.x.x
npm --version   # 10.x.x

Install Hexo CLI

1
npm install -g hexo-cli

Create a New Site

1
2
3
hexo init my-blog
cd my-blog
npm install

The resulting directory tree:

1
2
3
4
5
6
7
8
9
10
my-blog/
├── _config.yml        # Site configuration
├── package.json
├── scaffolds/         # Post/page/draft templates
│   ├── post.md
│   ├── page.md
│   └── draft.md
├── source/
│   └── _posts/        # Your Markdown content
└── themes/            # Theme directory

Core Concepts

Front Matter

Every post and page starts with YAML front matter:

1
2
3
4
5
6
7
8
9
---
title: My First Post
date: 2025-01-20 10:00:00
categories:
  - Development
tags:
  - hexo
  - guide
---

Creating Content

1
2
3
4
5
6
7
8
9
10
11
# New post
hexo new post "Building a Blog with Hexo"

# New page
hexo new page about

# New draft
hexo new draft "Work in Progress"

# Publish a draft
hexo publish "Work in Progress"

The <!-- more --> Tag

Insert <!-- more --> anywhere in a post body to define the excerpt boundary. Everything before the tag appears on the index page:

1
2
3
4
5
This is the excerpt shown on the homepage.

<!-- more -->

This content is only visible on the full post page.

Configuration

The root _config.yml controls site-wide settings:

1
2
3
4
5
6
7
8
9
10
11
12
title: My Blog
subtitle: Writing about things I find interesting
author: Your Name
url: https://yourblog.com
permalink: :year/:month/:day/:title/

theme: vaultex

# Pagination
index_generator:
  per_page: 10
  order_by: -date

Plugins

These three plugins complement Vaultex:

1
npm install hexo-generator-search hexo-generator-feed hexo-generator-sitemap

Add to _config.yml:

1
2
3
4
5
6
7
8
9
10
11
12
search:
  path: search.xml
  field: post
  content: true

feed:
  type: atom
  path: atom.xml
  limit: 20

sitemap:
  path: sitemap.xml

Development Server

1
2
3
hexo server
# or shorter:
hexo s

The server starts at http://localhost:4000 and reloads on file changes (with a few seconds of latency for large sites).

Building for Production

1
2
3
4
hexo clean  # clear the public/ cache
hexo generate
# or shorter:
hexo g

Output goes to public/. Deploy anywhere that serves static files: GitHub Pages, Netlify, Vercel, Cloudflare Pages, or your own nginx server.

Deployment Targets

Hexo has built-in deployers for common targets:

Target Plugin
GitHub Pages hexo-deployer-git
Netlify Native — just push to git
Vercel Native — just push to git
FTP/SFTP hexo-deployer-ftpsync
Rsync hexo-deployer-rsync

For GitHub Pages:

1
npm install hexo-deployer-git
1
2
3
4
5
# _config.yml
deploy:
  type: git
  repo: https://github.com/username/username.github.io
  branch: main
1
hexo deploy

Next Steps

Once your site is running:

  1. Install and configure a theme (like Vaultex)
  2. Create your About and Contact pages
  3. Write your first real post
  4. Set up a deployment pipeline (GitHub Actions works well)
  5. Add your domain and configure DNS