Hexo Blog Guide to Avoiding Pitfalls

Posted on Edited on In Word count in article: 1.5k Reading time ≈ 6 mins.

Recording and Summarizing the Pitfalls Encountered while Setting Up a Blog using HEXO and GitHub Pages

When setting up a blog, there are often challenges to overcome. While there are readily available blogging platforms, they might not always offer the desired level of control and ownership. After researching various tutorials from experienced bloggers, I decided to use GitHub Pages to create my own blog. GitHub Pages is introduced by GitHub itself.

This post was translated from my Chinese blog post with the aid of ChatGpt.

Configuration Process for GitHub Pages

  1. Register a GitHub Account: This is a straightforward step.
  2. Create a Repository: Name the repository after your username in the following format: username.github.io

    Pitfall:
    Make sure to use your exact username, as otherwise, the webpage won’t be generated.

  3. Create a README.md: You can write anything in this file.
  4. Click “Create Repository”: After creating, proceed to the next step.
  5. Access “Settings”: Inside the repository, navigate to “Settings.”
  6. Enable GitHub Pages and Choose a Theme: Under “GitHub Pages,” click “Choose a theme” and select any theme for now. You can change it later.
  7. Preview Your Site: Now, opening username.github.io will display your webpage.

Local Software Configuration

To work locally, you need to install the following software:

  • Git
  • Node.js
  • Markdown Editor (I personally use Haroopad)

You can download the above software from their official websites. After installation, open your terminal and type the following commands to check their versions:

  • git --version
  • node -v

If the installation is successful, you’ll see the version numbers returned. The specific versions might vary, but it won’t affect their functionality. The installation of the Markdown Editor is usually straightforward—just run the .exe file.

In the end, the local software setup should look something like this:

  • Git version: 2.21.0.windows.1
  • Node.js version: v10.15.3

Configuration Process for HEXO

HEXO is a blogging framework, and the steps are as follows:

  1. Create a Folder for Web Information: Set up a folder to store webpage data.
  2. Open Git Bash Inside the Folder: Right-click inside the folder and select “Git Bash.”
  3. Install HEXO: Enter the command npm install hexo -g to install HEXO globally.
  4. Check Installation: Enter hexo -v to check if the installation was successful. You should see a version number.
  5. Initialize HEXO: Enter hexo init to initialize HEXO.

    Pitfall:
    Due to some mysterious forces, this process might take a very long time. You can accelerate it by using a Taobao source. During this waiting period, don’t assume it’s stuck and close the process. If you do, you’ll need to delete the blog directory and start over because restarting the process will lead to continuous errors.

  6. Install Dependencies: Enter npm install to install additional files.
  7. Install Deployment Plugin: Enter npm install hexo-deployer-git --save to install the deployment plugin.
  8. Generate Webpage: Enter hexo g to generate webpages.
  9. Start Local Server: Enter hexo s to start a local server. It will return a URL like http://localhost:4000.
  10. Preview the Site: Copy the URL and open it in a browser to preview the webpage.
  11. Deploy to GitHub Pages: Enter hexo d to deploy to GitHub Pages.
  12. Access Your Website: Enter username.github.io in your browser to access the website. If deployment is unsuccessful, GitHub will send you an email notification.

Theme Customization

HEXO offers a variety of themes to choose from. You can search for HEXO themes on GitHub or visit the HEXO official website for options. Here, I’ll use the Matery theme as an example, with credits to the developer blinkfox.

Specific Steps

  1. Navigate to Your Blog Directory: Open Git Bash in your blog folder.
  2. Clone the Theme: Enter git clone https://github.com/blinkfox/hexo-theme-matery.git.

    Pitfall:
    Due to the same mysterious forces as before, GitHub download speed is painfully slow in certain regions—peaking at around 20kb/s, with 4kb/s being the norm. So, modifying the host file is necessary. Here’s how:

    • Use the IP Lookup tool on a site like https://www.ipaddress.com/ to obtain the IP addresses of the following GitHub domains (this site might require some magic to access):

      • github.com
      • github.global.ssl.fastly.net

    • IPs in China typically follow the format 192.30.xx.xx and 151.101.xx.xx.

    • Once you have the IP addresses, add the following entries to your hosts file, replacing the IPs with your findings:

      • 192.30.xx.xx github.com
      • 151.101.xx.xx github.global.ssl.fastly.net

    • Execute the command ipconfig /flushdns to refresh the DNS cache.

    After completing these steps, your download speed should improve significantly, reaching several hundred kb/s.

  3. Switch to the Theme: Modify the theme value in the _config.yml file in the root directory of your blog to theme: hexo-theme-matery.

    Pitfall:
    There must be a space after theme! Don’t forget it! Otherwise, the change won’t take effect. This file’s configuration follows strict syntax with a space after each colon. Finding errors here can be quite challenging.

  4. Further Configuration of Matery Theme: For detailed configuration of the Matery theme, refer to the Matery README.

Website Deployment

Once you’ve chosen a website theme, you can deploy it to your website.

Main Steps

  • Setting up SSH key pair
  • Purchasing and configuring a domain name
  • Deploying the website

Setting up SSH Key Pair

To ensure the security of your website, you need to set up SSH. After all, one of the main reasons for creating a personal blog is security. Here’s how:

  1. Open Git Bash
  2. Generate SSH Key Pair: Enter ssh-keygen -t rsa -C "email@example.com" and hit Enter three times.
  3. Locate SSH Key Files: In your user directory on the C drive, you’ll find two files: id_rsa and id_rsa.pub. You need the latter.
  4. Copy the Key: Open the id_rsa.pub file with Notepad and copy its entire contents.
  5. Add SSH Key on GitHub: Open GitHub, go to “Settings” in the dropdown menu under your profile picture.
  6. Open “SSH and GPG keys” and click “New SSH key” in the upper-right corner.
  7. Title can be anything, and paste the copied key into the Key field.
  8. Click Add SSH key.
  9. Go back to Git Bash and enter ssh -T git@github.com and hit Enter.
  10. You might get a prompt on the first attempt; enter yes and press Enter.
  11. If you see Hi username! You've successfully authenticated, but GitHub does not provide shell access., it means success.
  12. Enter git config --global user.name "Your Username"
  13. Enter git config --global user.email "your@email.com"

Purchasing and Configuring a Domain Name

GitHub’s provided domain name might be a bit too long and lacks sophistication, so setting up a memorable domain name is a good idea. Many websites offer domain services in China. I chose Alibaba Cloud, and here’s the process:

  1. Register on Alibaba Cloud: Sign up for an Alibaba Cloud account.

    Pitfall:
    Here, note that Alibaba Cloud prefers Chinese usernames. I initially used an English username and couldn’t get through. I succeeded only after using a Chinese one.

  2. Purchase a Domain: Buy a domain name you like, similar to the process on Taobao.
  3. Complete Domain Verification: Even though Alibaba Cloud says verification might take a few business days, mine was approved in ten minutes.
  4. Configure DNS: In the control panel, find your purchased domain and click “DNS Settings.”
  5. Add DNS Records: I added two records:
    • Select record type as A, hostname as @, and enter the IP address obtained from ping username.github.io in the Windows Command Prompt. Leave other settings as default.
    • Select record type as CNAME, hostname as www, and record value as username.github.io. Leave other settings as default.
  6. After configuring, go back to GitHub. In your webpage’s Repository, navigate to Settings, and under the GitHub Pages section, enter your purchased domain name under Custom domain.
  7. For convenience, create a CNAME file in your HEXO root directory. Inside, put your purchased domain name. This avoids repetitive input, as the domain name in Settings gets overwritten each time you deploy.

    Pitfall:
    The CNAME file should not have any extension; otherwise, it won’t work. I initially used CNAME.md, and the domain would get overwritten each time.

Deploying the Website

Finally, we’re at the last step. But before successfully deploying the website, there are a few minor tasks.

  1. Modify the —config.yml file under your HEXO root directory:
    1
    2
    3
    4
    deploy:
    type: git
    repository: https://github.com/username/username.github.io.git
    branch: master

    Pitfall:
    Again, ensure there’s a space after the colon here. Syntax matters!

  2. Open Git Bash.
  3. Enter hexo clean to clear the local browser cache.
  4. Enter hexo g to regenerate the website.
  5. Enter hexo s to generate a local preview.
  6. If the local preview is error-free, enter hexo d to deploy the website to GitHub Pages.
  7. If the returned result is git, congratulations! You’ve succeeded. You can now access your website using the previously associated domain name.

Mission Accomplished

I’ve filled most of the gaps. I’ll be updating more about basic HEXO usage and Markdown syntax. If I remember other pitfalls, I’ll make sure to add them. As I’m finishing this after a few days of setting up the blog, some details might be fuzzy. Feel free to reach out if you have questions!