Environment Setup

Installing Git

Download Git from git-scm.com and install the appropriate version for your system (32-bit or 64-bit).

Installing Node.js

Download Node.js from nodejs.org. After installation, verify by running:

node -v
npm -v

Restart your computer after installation completes.

Configuring Hexo

1. Create a new folder (e.g., E:\Projects\blog) and open Git Bash in that directory.

2. Install Hexo CLI globally:

npm install hexo-cli -g

Essential Hexo Commands

hexo g        # Generate static files
hexo s        # Start local server for preview
hexo d        # Deploy to remote repository
hexo n        # Create new post

3. Initialize the Hexo site:

hexo init
npm install

4. Generate files and start the preview server:

hexo g
hexo s

5. Open http://localhost:4000/ in your browser to preview.

Configuring the NexT Theme

Hexo has two primary configuration files named _config.yml. The site configuration file resides in the root directory, while the theme configuration file is located within the theme's folder.

Enabling NexT

Open the site configuration file and locate the theme field, then change its value to next:

theme: next

After making changes, regenerate and preview to see the NexT theme.

Appearance Settings

Open the theme configuration file and uncomment one of the Schemes under scheme::

scheme: Muse      # Default scheme, black and white with ample whitespace
scheme: Mist      # Compact single-column layout
scheme: Pisces    # Dual-column layout with fresh aesthetic

Important: Ensure a space exists after the colon in YAML syntax.

Language Configuration

In the site configuration file, find language and set your preferred language:

language: en          # English
language: zh-Hans     # Simplified Chinese
language: fr-FR       # French
language: pt          # Portuguese
language: zh-hk       # Traditional Chinese (Hong Kong)
language: zh-tw       # Traditional Chinese (Taiwan)
language: ru          # Russian
language: de          # German
language: ja          # Japanese
language: id          # Indonesian
language: ko          # Korean

Menu Configuration

In the theme configuration file, locate menu to configure main navigation items:

menu:
  home: /              # Homepage
  archives: /archives  # Archives
  categories: /categories  # Categories page
  tags: /tags         # Tags page
  about: /about       # About page
  commonweal: /404.html  # Charity 404 page

To display translated labels, edit the appropriate language file under languages/{language}.yml. For example, if using language: zh-Hans, edit zh-Hans.yml.

Additional Configurations

Avatar

In the theme configuration file, set the avatar path:

avatar: /images/profile.png

Place your avatar image in hexo/public/images/.

Author Information

Set author name and description in the site configuration file:

title: My Blog
subtitle: Technical writings
author: Your Name
description: Blog description

Analytics

Register at Baidu Tongji, add your website, then copy the tracking ID (from hm.js? onwards) and add it to the theme configuration file:

baidu_analytics: your_tracking_id

Social Links

In the theme configuration file, configure social with your profiles:

social:
  GitHub: https://github.com/username
  Twitter: https://twitter.com/username

Creating Pages

Run these commands in your site directory to create pages:

hexo new page "categories"
hexo new page "tags"
hexo new page "about"

Navigate to source/categories/, source/tags/, and source/about/ folders. Edit the index.md file in each to add Chinese labels and set comments: false if needed.

Deploying to GitHub

Creating a GitHub Repository

1. Sign in to GitHub and create a new repository named username.github.io, replacing username with your GitHub username.

2. After creation, go to repository Settings > Pages. Select a theme or use the main branch as your source. Your site will be accessible at username.github.io.

Connecting Hexo to GitHub

Configure Git global settings:

git config --global user.name "your_username"
git config --global user.email "your_email"

Open the site configuration file and add the repository URL under deploy::

deploy:
  type: git
  repo: git@github.com:username/username.github.io.git

Install the Git deployment plugin:

npm install hexo-deployer-git --save

Publishing Content

Create a new post:

hexo new post "Hello World"

This generates a Markdown file in source/_posts/. Edit the frontmatter:

---
title: Hello World
date: 2023-10-05 14:50:33
categories: general
tags: [hello, introduction]
---

Your content here...

Preview locally:

hexo g
hexo s

Deploy to GitHub:

hexo d

Your post will be live at username.github.io.

Configuring a Custom Domain

Registering a Domain

Purchase a domain from a registrar such as Alibaba Cloud. Search for availability—.com is recommended if available.

DNS Configuration

GitHub's IP addresses are 192.30.252.153 and 192.30.252.154. In your DNS settings, add an A record:

Record Type	Host	Value
A	www	192.30.252.153

Save the DNS configuration and wait for propagation.

GitHub CNAME Setup

Create a file named CNAME (no extension) in your repository's root or in source/ directory containing your domain:

example.com

When deploying via Hexo, add the CNAME file to source/ so it persists after regeneration.

Troubleshooting

YAML Parsing Error: "FATAL can not read a block mapping entry"

Check _config.yml for correct YAML syntax. Ensure every colon has a space after it.

Deployer Not Found Error

Install the deployment plugin:

npm install hexo-deployer-git --save

CNAME File Lost After Deployment

Place the CNAME file in the source/ directory. Hexo will copy it to public/ during generation.

References

• Hexo Documentation
• NexT Theme Documentation
• GitHub Pages Setup