Hexo

Hexo Site Management Skill

This skill helps you manage Hexo static blog sites, including initialization, content creation, custom layouts, and publishing.

Overview

Hexo is a fast, simple, and powerful blog framework that generates static HTML files from Markdown content. This skill provides guidance for common Hexo operations.

Requirements

Before using Hexo commands, ensure:

• Node.js 20.19.0+ is installed
• Git is installed
• hexo-cli is installed globally: npm install -g hexo-cli

Core Operations

1. Initialize a New Hexo Site

To create a brand new Hexo site:

hexo init [folder-name]
cd [folder-name]
npm install

This creates the following structure:

.
├── _config.yml          # Main configuration
├── package.json
├── scaffolds/           # Post templates
├── source/              # Source files
│   ├── _drafts/        # Draft posts
│   └── _posts/         # Published posts
└── themes/             # Site themes

After initialization:

1. Configure _config.yml with site title, description, author, URL, etc.
2. Review and customize the theme settings
3. Start the development server: hexo server

2. Create Posts

Create a new post:

hexo new post "Post Title"
# Creates: source/_posts/Post-Title.md

Create a new page:

hexo new page "about"
# Creates: source/about/index.md

Create a draft:

hexo new draft "Draft Title"
# Creates: source/_drafts/Draft-Title.md

Publish a draft:

hexo publish draft "Draft Title"
# Moves from _drafts to _posts

3. Front-Matter

All posts begin with front-matter in YAML format:

---
title: Post Title
date: 2026-03-05 12:00:00
updated: 2026-03-05 12:00:00
tags:
  - tag1
  - tag2
categories:
  - category1
  - category2
layout: post
comments: true
permalink: custom-url-path
excerpt: A brief summary of the post
---

Key fields:

• layout: Template to use (post, page, or custom)
• title: Post heading
• date: Publication timestamp
• tags: Single-level labels (posts only)
• categories: Hierarchical classifications (posts only)
• permalink: Custom URL override
• excerpt: Summary text
• comments: Enable/disable comments (default: true)
• published: Visibility control (default: true)

See [references/front-matter.md](references/front-matter.md) for complete details.

4. Custom Layouts & Scaffolds

Scaffolds are templates in the scaffolds/ folder that define the structure of new posts.

Default scaffolds:

• post.md - Used for regular posts
• page.md - Used for pages
• draft.md - Used for drafts

Create a custom scaffold:

1. Create a new file in scaffolds/, e.g., scaffolds/photo.md:

---
layout: {{ layout }}
title: {{ title }}
date: {{ date }}
tags:
photos:
---

1. Use it when creating content:

hexo new photo "My Photo Gallery"

Available placeholders in scaffolds:

• {{ layout }} - Layout name
• {{ title }} - Post title
• {{ date }} - Creation date

Example custom layouts:

• photo.md - Photo gallery posts
• video.md - Video posts
• link.md - Link posts
• quote.md - Quote posts

See [examples/custom-scaffold.md](examples/custom-scaffold.md) for examples.

5. Generate & Serve

Run local development server:

hexo server
# or
hexo s

# Options:
# -p, --port     Custom port (default: 4000)
# -s, --static   Static mode only
# -l, --log      Enable logger
# -d, --drafts   Display draft posts

Access site at: http://localhost:4000

Generate static files:

hexo generate
# or
hexo g

# Options:
# -d, --deploy   Deploy after generation
# -w, --watch    Watch file changes

Generated files are in public/ directory.

Clean cache and generated files:

hexo clean

Always run hexo clean before regenerating if you encounter issues.

6. Deploy

Generate and deploy in one command:

hexo deploy
# or
hexo d

# Combined generation + deployment:
hexo generate --deploy
# or
hexo g -d

Basic deployment configuration in _config.yml:

deploy:
  type: git
  repo: 
  branch: gh-pages
  message: "Site updated: {{ now('YYYY-MM-DD HH:mm:ss') }}"

For complete GitHub Pages deployment guide, including:

• GitHub Actions setup (recommended)
• hexo-deployer-git configuration
• Authentication methods (SSH, tokens)
• Custom domain setup
• Troubleshooting

See: [GitHub Pages Deployment Guide](references/github-pages-deployment.md)

Common Workflows

Starting a New Hexo Blog

# 1. Install Hexo CLI globally
npm install -g hexo-cli

# 2. Create new site
hexo init my-blog
cd my-blog
npm install

# 3. Configure site
# Edit _config.yml with your details

# 4. Create first post
hexo new post "Hello Hexo"

# 5. Start development server
hexo server

Publishing a New Post

# 1. Create draft
hexo new draft "My New Post"

# 2. Edit source/_drafts/My-New-Post.md
# Add content and front-matter

# 3. Preview with drafts visible
hexo server --drafts

# 4. Publish when ready
hexo publish draft "My New Post"

# 5. Generate and deploy
hexo clean && hexo generate --deploy

Creating a Custom Layout

# 1. Create scaffold template
cat > scaffolds/project.md ` | List all routes |
| `hexo version` | Show version info |

**Global options:**
- `--draft` - Display draft posts
- `--safe` - Disable plugins
- `--debug` - Verbose logging
- `--silent` - Suppress output
- `--config` - Custom config file
- `--cwd` - Custom working directory

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [linkcd](https://github.com/linkcd)
- **Source:** [linkcd/hexo-skill](https://github.com/linkcd/hexo-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.