1704701477603

Official Documentation: https://hexo.io/docs/

Prerequisites

You will need:

  1. Node.js (12.0 or higher)
  2. Git

To check your environment, please enter the following commands and ensure you get similar return results:

1
2
3
4
5
6
7
8
git -v
# git version 2.xx.x

node -v
# v18.xx.x

npm -v
# 10.x.x

Initialize Project

Navigate to the path where you want to store your blog source code and perform the following operations:

1
2
3
hexo init <folder>
cd <folder>
npm install

After initialization, the directory structure should be as follows:

1
2
3
4
5
6
7
8
.
├── _config.yml
├── package.json
├── scaffolds
├── source
|   ├── _drafts
|   └── _posts
└── themes

Install Dependencies

I personally prefer to use pnpm, but npm and yarn should be fine as well.

The differences between Npm, Yarn, and Pnpm can be seen in TODO

1
pnpm install

Running the Project

Script Explanation

Open package.json, and you will find the following scripts:

1
2
3
4
5
6
7
8
9
10
{
  ...
  "scripts": {
    "build": "hexo generate",
    "clean": "hexo clean",
    "deploy": "hexo deploy",
    "server": "hexo server"
  },
  ...
}

They correspond to:

  • build: Generate static web page resources (public).
  • clean: Clear the cache, mainly db.json and public.
  • deploy: Deploy, when used in conjunction with hexo-deployer-git, it will push static web page resources to a specified git project. Commonly used for Github Pages service.
  • server: Local debugging and running.

Running the Project

Execute the server script (pnpm run server or use the interactive button in the IDE) to run the project locally.

Under normal circumstances, you will get an output like this in the console:

1
2
3
4
5
6
...
pnpm run server
$ hexo server
INFO  Validating config
INFO  Start processing
INFO  Hexo is running at http://localhost:4000/ . Press Ctrl+C to stop.

At this point, if you visit http://localhost:4000/ in your browser, you should be able to see your blog homepage.

1704700921055

Deployment

Reference Documentation: https://hexo.io/docs/one-command-deployment

Use hexo-deployer-git (Official Documentation) in conjunction with *
GitHub Pages* (Official Documentation) service

1. Configure Github Pages

See TODO

2. Configure Local SSH-Key for Github

See TODO

3. Install hexo-deployer-git

1
2
# Run in the root directory of the project:
pnpm install hexo-deployer-git --save

4. Configure _config.yml

Edit the _config.yml file in the root directory, and find the following section:

1
2
deploy:
  type: ''

If there is no deploy: , add it manually.

Modify this configuration as follows:

1
2
3
4
deploy:
  type: git
  repo: git@github.com:<Your-Github-Name>/<Your-Github-Name>github.io.git # Replace <Your-Github-Name> with your Github username
  branch: main

5. Deploy the Project to Github Pages

  1. Run hexo deploy or pnpm run deploy.
  2. Visit your-github-name.github.io (replace your-github-name with your Github username).

6. (Optional) Resolving Conflicts with Custom Domain CNAME in Github Pages

When a custom domain is configured for Github Pages, Github automatically commits a record named Create CNAME to the project.

Since hexo-deployer-git is a one-way automated push, we cannot receive this commit.

Therefore, the remedy is to manually download the CNAME file (or create a new file with the same name and copy its contents) and place it in the source directory.