Hexo Static Site Generator - Commands and Themes

Hexo is a fast, simple and powerful blog framework powered by Node.js. This guide covers the essential commands and workflow, plus a curated list of excellent themes to get you started.

Quick Start

Create a New Post

1
2
3
4
5
6
hexo new "My New Post"

# Or with a specific layout
hexo new post "My New Post"
hexo new draft "Work in Progress"
hexo new page "About Me"

Creates a new markdown file in source/_posts/ with frontmatter template.

More info: Writing

Run Development Server

1
2
3
4
5
6
7
8
9
10
hexo server

# Or short form
hexo s

# With custom port
hexo server -p 5000

# Open in browser automatically
hexo server -o

Starts local server at http://localhost:4000 for previewing your site.

More info: Server

Generate Static Files

1
2
3
4
5
6
7
hexo generate

# Or short form
hexo g

# With file watching for auto-regeneration
hexo generate --watch

Generates static HTML files in the public/ directory.

More info: Generating

Deploy to Remote Sites

1
2
3
4
5
6
7
8
9
hexo deploy

# Or short form
hexo d

# Generate and deploy in one command
hexo generate --deploy
# or
hexo g -d

Deploys your site to configured hosting (GitHub Pages, Netlify, etc.).

More info: Deployment

Common Workflow

Clean and Regenerate

1
2
3
4
5
# Clean cached files and generated static files
hexo clean

# Then regenerate
hexo generate

Use this when you change config or encounter rendering issues.

Development Workflow

1
2
3
4
5
6
7
8
# Start with clean slate
hexo clean

# Generate and start server with watch mode
hexo generate --watch & hexo server

# Or use concurrently
hexo server --draft  # Include draft posts in preview

Deployment Workflow

1
2
3
4
5
6
7
8
# Test locally first
hexo clean && hexo generate && hexo server

# Then deploy
hexo deploy

# Or combined
hexo clean && hexo generate --deploy

Writing Content

Markdown Syntax

Hexo uses Markdown for content. Quick reference:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# Heading 1
## Heading 2
### Heading 3

**Bold text**
*Italic text*
~~Strikethrough~~

- Unordered list
- Another item

1. Ordered list
2. Another item

[Link text](https://example.com)
![Image alt text](/images/photo.jpg)

`inline code`

\```javascript
// Code block
console.log('Hello World');
\```

> Blockquote

Complete guide: Markdown Syntax

Post Frontmatter

1
2
3
4
5
6
7
8
9
10
11
---
title: My Post Title
date: 2025-12-29 10:00:00
updated: 2025-12-29 15:30:00
tags:
  - tutorial
  - hexo
categories:
  - Web Development
excerpt: Brief description for preview
---

Tags and Categories

1
2
3
4
5
6
7
8
9
10
11
12
# Create a new post with tags
hexo new "My Post" --tag tutorial,hexo,web

# Tags in frontmatter (multiple ways)
tags: tutorial
# or
tags: [tutorial, hexo, web]
# or
tags:
  - tutorial
  - hexo
  - web

Configuration Tips

_config.yml Essentials

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# Site
title: Your Blog Name
subtitle: Your Subtitle
description: SEO description
author: Your Name
language: en
timezone: America/New_York

# URL
url: https://yourdomain.com
permalink: :year/:month/:day/:title/

# Writing
new_post_name: :title.md
default_layout: post
auto_spacing: true
titlecase: true

# Server
port: 4000

Theme Configuration

Each theme has its own _config.yml in themes/theme-name/ directory. Common settings:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# Navigation menu
menu:
  Home: /
  Archives: /archives
  About: /about

# Sidebar widgets
widgets:
  - category
  - tag
  - archive
  - recent_posts

# Social links
social:
  GitHub: https://github.com/username
  Twitter: https://twitter.com/username

Production-Ready Themes

Cactus - Minimalist Blog Theme

Obsidian - Modern & Feature-Rich

Meadow - Elegant & Simple

3-Hexo - Advanced Features

Installing a Theme

1
2
3
4
5
6
7
8
9
10
11
12
13
# Clone theme into themes directory
cd your-hexo-site
git clone https://github.com/probberechts/hexo-theme-cactus themes/cactus

# Install theme dependencies (if any)
cd themes/cactus
npm install

# Update _config.yml
theme: cactus

# Regenerate site
hexo clean && hexo generate && hexo server

Choosing a Theme

Consider these factors:

  1. Design Style

    • Minimalist vs. feature-rich
    • Light vs. dark vs. both
    • Typography preferences

  2. Features Needed

    • Comments (Disqus, Gitalk, etc.)
    • Search functionality
    • Analytics integration
    • Social sharing buttons
    • Code syntax highlighting

  3. Performance

    • Page load speed
    • Mobile responsiveness
    • SEO optimization

  4. Maintenance

    • Last updated date
    • Active development
    • Community support
    • Documentation quality

  5. Customization

    • Easy color changes
    • Layout options
    • Widget flexibility

Essential Plugins

Extend Hexo functionality with plugins:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# SEO
npm install hexo-seo --save

# Sitemap generation
npm install hexo-generator-sitemap --save

# RSS feed
npm install hexo-generator-feed --save

# Search
npm install hexo-generator-search --save

# Image optimization
npm install hexo-image-sizes --save

# Related posts
npm install hexo-related-posts --save

Troubleshooting

Port Already in Use

1
2
3
4
5
# Kill process on port 4000
lsof -ti:4000 | xargs kill -9

# Or use different port
hexo server -p 5000

Changes Not Showing

1
2
3
4
5
6
7
8
# Clear cache and regenerate
hexo clean && hexo generate

# Check if files are generated
ls public/

# Restart server
hexo server

Theme Not Loading

1
2
3
4
5
6
7
8
# Verify theme directory
ls themes/

# Check theme name in _config.yml
grep "^theme:" _config.yml

# Install theme dependencies
cd themes/your-theme && npm install

Deployment Issues

1
2
3
4
5
6
7
8
9
10
# Clean before deploying
hexo clean

# Generate fresh files
hexo generate

# Deploy
hexo deploy

# Check deployment config in _config.yml

Quick Reference

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
# Installation
npm install -g hexo-cli
hexo init my-blog
cd my-blog
npm install

# Create content
hexo new "Post Title"
hexo new page "about"
hexo new draft "Draft Title"

# Development
hexo server                 # Start server
hexo server --draft        # Include drafts
hexo server -p 5000        # Custom port

# Generation
hexo generate              # Generate files
hexo generate --watch      # Auto-regenerate on changes
hexo clean                 # Clean cache

# Deployment
hexo deploy                # Deploy
hexo generate --deploy     # Generate & deploy

# Combined commands
hexo clean && hexo generate && hexo deploy
hexo g -d                  # Short form of above

# Help
hexo help                  # Show all commands
hexo help generate         # Help for specific command
hexo version              # Show version

Conclusion

Hexo provides a powerful yet simple platform for creating static websites. Key points:

  • Use hexo clean when you encounter issues
  • Test locally with hexo server before deploying
  • Choose a theme that fits your needs and style
  • Keep your Hexo and plugins updated
  • Leverage Markdown for easy content creation
  • Deploy frequently to keep your site fresh

Start with the basic commands, pick a nice theme, and customize as you go. Hexo’s flexibility allows you to grow from a simple blog to a complex website as your needs evolve.