GitHub Repository Configuration

Begin by establishing a dedicated repository on GitHub to host the static files. Navigate to the platform and initialize a new repository. The repository name must strictly follow the handle.github.io pattern, where handle matches your GitHub account username exactly. This naming convention triggers GitHub Pages automatically.

Environment Preparation

Hexo operates on Node.js and requires Git for version control and deployment. Install Git through your system's package manager or official installer. For Node.js, utilize a version manager like nvm to handle runtime versions efficiently:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts

Once the runtime is active, install the Hexo command-line interface globally:

npm install -g hexo-cli

Project Initialization & Configuration

Generate the project scaffold by executing the enitialization command. Replace devhandle with your actual GitHub username:

hexo init devhandle.github.io
cd devhandle.github.io

Open the root _config.yml file to adjust core parameters. Ensure proper YAML spacing:

title: Technical Notes
author: Alex Chen
language: en
theme: landscape
deploy:
  type: git
  repo: https://github.com/devhandle/devhandle.github.io.git
  branch: main

Theme Integration

Navigate to the project root and clone a theme into the themes directory. For example, integrtaing the NexT theme:

git clone https://github.com/next-theme/hexo-theme-next themes/next

Update the theme field in the root configuration file to next. Theme-specific adjustments can be made in themes/next/_config.yml.

Content Creation & Local Testing

Draft articles inside the source/_posts directory using Markdown. Create a file named getting-started.md:

---
title: Initial Setup Log
date: 2023-10-25
---
Exploring the fundamentals of static site generation.

Launch the local development server to verify rendering:

hexo server

Access http://localhost:4000 in a browser. If dependencies are missing, resolve them with:

npm install hexo-renderer-marked hexo-generator-feed hexo-generator-sitemap --save

Deployment Workflow

Enstall the Git deployment plugin:

npm install hexo-deployer-git --save

Compile the static assets and push them to the remote repository:

hexo clean && hexo generate && hexo deploy

The terminal will prompt for credentials on the first run. Subsequent executions will automatically sync updated content.

Troubleshooting Common Issues

Template Rendering Fails After Theme Switch

Hexo v5+ removed the Swig engine by default. Reinstall it manually:

npm install hexo-renderer-swig --save

Deployer Not Found Error

This occurs when the deployment plugin is missing. Execute:

npm install hexo-deployer-git --save

Authentication Rejection During Push

GitHub deprecated password authentication for HTTPS. Switch the repository URL in _config.yml to use SSH or a Personal Access Token (PAT):

deploy:
  type: git
  repo: https://YOUR_TOKEN@github.com/devhandle/devhandle.github.io.git

Alternatively, use the SSH format: git@github.com:devhandle/devhandle.github.io.git.

SSL Certificate Verification Failure

If Git throws a certificate path error, reconfigure the CA bundle location or bypass verification (not recommended for production):

git config --global http.sslcainfo "/path/to/curl-ca-bundle.crt"
# Or disable verification temporarily
git config --global http.sslverify false