build-website

发表于 更新于

A Complete Guide to Building Your Personal Website with Hexo, NexT, and GitHub Pages

Creating a personal website is a fantastic way to showcase your portfolio, write blogs, and share your knowledge. In this tutorial, we will use Hexo (a fast, simple, and powerful blog framework powered by Node.js), the elegant NexT theme, and GitHub Pages for free hosting.

Prerequisites

Before we begin, ensure you have the following installed on your computer: 1. Node.js (includes npm) 2. Git 3. A GitHub Account

Step 1: Create a GitHub Repository

First, we need a place to host your website. GitHub Pages requires a specific repository name to work out of the box.

  1. Log in to your GitHub account.
  2. Click the New button to create a new repository.
  3. Repository name: This is crucial. You MUST name it your-github-username.github.io. (Replace your-github-username with your actual exact username).
  4. Make the repository Public.
  5. Click Create repository.

Step 2: Install Hexo and Initialize Your Site

Now, let’s set up Hexo on your local machine. Open your terminal or command prompt.

  1. Install Hexo CLI globally: 
    1
    npm install -g hexo-cli
  2. Initialize your blog directory: Navigate to the folder where you want to keep your website files and run: 
    1
    2
    3
    hexo init my-blog
    cd my-blog
    npm install

Understanding the Directory Structure

After initialization, your my-blog folder will look like this:

1
2
3
4
5
6
7
8
my-blog/
├── _config.yml         <-- ⚠️ Site Configuration File (Hexo Config)
├── package.json        <-- Application data and installed plugins
├── scaffolds/          <-- Templates when creating new posts
├── source/             <-- 📝 Where you write your content (Markdown files)
│   ├── _drafts/
│   └── _posts/         <-- Your blog posts go here
└── themes/             <-- 🎨 Downloaded themes go here

Step 3: Install the NexT Theme

NexT is one of the most popular, clean, and feature-rich themes for Hexo.

  1. Inside your my-blog directory, download the NexT theme using Git: 
    1
    git clone https://github.com/next-theme/hexo-theme-next themes/next

⚠️ The Golden Rule: Distinguishing the Two _config.yml Files

The most common source of confusion in Hexo is having two main configuration files. You must understand the difference:

  1. The Site Config (Hexo Config):
    • Location: my-blog/_config.yml (Root directory)
    • Purpose: Controls site-wide settings like the title, author, URL, language, and deployment settings.
    • Action: Open this file and change the theme variable: 
      1
      2
      # my-blog/_config.yml
      theme: next
  2. The Theme Config (NexT Config):
    • Location: my-blog/themes/next/_config.yml
    • Purpose: Controls the visual appearance, menu items, sidebars, social links, and integrations (like MathJax for math equations) specifically for the NexT theme.

Step 4: Perfecting LaTeX Rendering (Inline & Display Equations)

By default, Hexo’s standard Markdown renderer (hexo-renderer-marked) conflicts with LaTeX syntax (specifically, it treats underscores _ as italics, which breaks math subscripts like Xi).

Here is the bulletproof way to fix this and render beautiful math.

1. Swap the Renderer

Uninstall the default renderer and install a math-friendly one (hexo-renderer-kramed is highly recommended for this):

1
2
npm uninstall hexo-renderer-marked --save
npm install hexo-renderer-kramed --save

2. Enable MathJax in the NexT Config

Open your Theme Config (my-blog/themes/next/_config.yml), find the math section, and enable MathJax:

1
2
3
4
5
6
7
8
9
10
# my-blog/themes/next/_config.yml
math:
  # Default (true) will load mathjax / katex script on demand.
  # That is it only render those page which has `mathjax: true` in Front-matter.
  every_page: false

  mathjax:
    enable: true
    # Available values: mathjax | mhchem
    tags: none

3. Using LaTeX in Your Posts

Because we set every_page: false to save loading times, you must add mathjax: true to the Front-matter (the top section) of any Markdown file where you want to write formulas.

Create a new post: 

1
hexo new "My Math Post"

Open source/_posts/My-Math-Post.md and write:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
---
title: My Math Post
date: 2026-04-10 10:00:00
tags:
mathjax: true  <-- MUST ADD THIS
---

Here is an inline equation: $E = mc^2$. It renders perfectly in the flow of text.

Here is a display equation block:

$$
f(x) = \int_{-\infty}^\infty \hat{f}(\xi)\,e^{2 \pi i \xi x} \,d\xi
$$

Step 5: Deploying to GitHub Pages

You have your site and your math looks great. Let’s push it to the internet.

  1. Install the deployment plugin: 

    1
    npm install hexo-deployer-git --save

  2. Configure Deployment: Open your Site Config (my-blog/_config.yml), scroll to the very bottom, and modify the deploy section. Add your repository URL:

    1
    2
    3
    4
    5
    # my-blog/_config.yml
    deploy:
      type: git
      repo: https://github.com/your-github-username/your-github-username.github.io.git
      branch: main # or master, depending on your GitHub default branch

  3. Deploy! Run the following commands to clean old files, generate the new HTML, and push it to GitHub: 

    1
    2
    3
    hexo clean
    hexo generate
    hexo deploy
    (Note: You will be prompted to log in to your GitHub account during the deploy step if you haven’t authenticated in your terminal).

Wait a few minutes, visit https://your-github-username.github.io, and your new personal website will be live!

📌 Hexo Cheat Sheet: Common Commands

Keep these commands handy as you write and maintain your blog:

  • hexo new "Post Title" (or hexo n): Creates a new .md file in source/_posts/.
  • hexo server (or hexo s): Starts a local server at http://localhost:4000 so you can preview your site before publishing.
  • hexo clean: Deletes the public/ and db.json files. Do this if your changes aren’t showing up.
  • hexo generate (or hexo g): Builds the static HTML files from your Markdown.
  • hexo deploy (or hexo d): Pushes the generated files to GitHub.
  • hexo clean && hexo g && hexo d: The holy trinity. Cleans, generates, and deploys all in one go.
  • hexo deploy --message "Your commit message" (or hexo d -m "Your commit message"): Deploy with a custom commit message.