How can we build a blog with Hexo + GitHub + Netlify

Posted on Edited on Views:

Why did I choose Hexo + GitHub + Netlify?

Hexo

Hexo is a fast, simple & powerful blog framework which can help us to generate the static files of blog and deploy the sites. The reason why I choose Hexo is only NexT theme of Hexo.

GitHub

I use GitHub to manage all the articles of my blog and regard it as a Cloud Drive to sync files.

Netlify

The reasons why I choose Netlify are:

  • It can help me to generate and deploy the sites automatically, which means that I don’t need to memorize the command of Hexo such as hexo generate and hexo deploy. I only need to git push my articles to my repo on GitHub.
  • I can add my customized domain so easily. It can address DNS verification problem and also https problem in a very simple way.

Alternatively, you can also choose GitHub Pages (Maybe I will move my blog to GitHub Pages in the future).

Steps to build your own blog

Node.js and Git

Installation

You should install Node.js and Git on your own laptop first. It’s recommended to follow the official website of Node.js and Git.

Here I also recommend to install GitHub Desktop because of its convenience.

GitHub

New repo

Create a new repo for storing all the files of your blog.

Note that you should not name your repo as yourname.github.io if you want to use Netlify. Because if you use yourname.github.io as your repo name, GitHub will regards it as a GitHub Page automatically and do GitHub Actions (Build with Jekyll) to deploy the site automatically.

Also you should set the repo as Public and without README.md file.

Here because I have created the repo named blog, it said that the repo exists on my account.

New SSH key

First you need to set the configurations of git on your laptop:

1
2
git config --global user.name "your_name"
git config --global user.email "your_email"

And then you need to generate a SSH key on your labtop using:

1
ssh-keygen -t rsa -C "your_email"

Open your profile of your GitHub. Click settings -> SSH and GPG keys -> New SSH key. You can set any name of title. Return to the bash and input:

1
cat ~/.ssh/id_rsa.pub

Copy the output to Key box. And Click Add SSH key.

Finally, for testing whether you have added SSH key successfully, you can use:

1
ssh -T git@github.com

If you can see your username of GitHub, you have added SSH key successfully.

Hexo

Installation

It is highly recommended that you follow the steps on the Hexo official website to install Hexo.

What you need to do is just:

1
2
3
4
npm install hexo-cli -g
hexo init blog
cd blog
npm install

Note that blog in hexo init blog and cd blog is the folder name of your blog. You can customize it such as hexo init myblog.

NexT Theme

Installation

Follow the official instructions to install NexT Theme.

I also recommend the first method that mentioned in it.

1
2
cd blog
npm install hexo-theme-next

Note that if you install NexT in this way (npm), the theme will appear in the node_modules folder. If you install NexT in the second way (git), it will appear in the theme folder.

Configure your NexT Theme

Follow the official docs of Configuration of NexT Theme.

  1. Please ensure you are using Hexo 5.0 or later.

  2. Create a config file in site’s root directory, e.g. _config.next.yml.

  3. Copy needed NexT theme options from NexT config file into this config file. If it is the first time to install NexT, then copy the whole NexT config file by the following command:

    1
    2
    3
    4
    # Installed through npm
    cp node_modules/hexo-theme-next/_config.yml _config.next.yml
    # Installed through Git
    cp themes/next/_config.yml _config.next.yml

Configuration of Hexo

Then, we need to set some configurations of Hexo.

Open the configuration file _config.yml in your blog folder. And set the variables as follows:

1
2
3
4
5
6
7
8
# Site
title: your_site_name
subtitle: ''
description: ''
keywords:
author: your_name
language: en
timezone: ''

And also:

1
2
3
4
5
6
7
8
9
## Themes: https://hexo.io/themes/
theme: next

# Deployment
## Docs: https://hexo.io/docs/one-command-deployment
deploy:
  type: git
  repository: git@github.com:username/reponame.git
  branch: main

Note that the repository attribute should be SSH version of GitHub repo. If you use HTTPS version of GitHub repo, you will be asked to input the username and password of GitHub and also will fail to deploy your blog site because you will need to create Personal access tokens in the Developer settings of GitHub.

Push Blog to GitHub

Before we push the blog to GitHub, we need to make sure two things:

  • Add a README.md file manually and put it in the blog root folder.

  • Make sure you have a .gitignore file in the blog root folder.

Then you can push the blog files to GitHub just as follows:

1
2
3
4
5
6
cd blog
git init .
git commit -m "init"
git branch -M main
git remote add origin git@github…..git
git push -u origin main

Note that you should not run hexo generate or hexo g or hexo d because Netlify will help us to generate and deploy the site automatically using the build command hexo generate.

Netlify

Deploy your blog site

Log in Netlify website, select import from an exitsting project and select GitHub. Choose the repo that you created just now (whose name is not username.github.io). And set Build command to hexo generate and set Publish directory to public as follows:

Then the site has been successfully deployed.

Custom domains

You can easily customize your own domain in Domain management on the side bar or the guide page if you deploy your site first time.

DNS verification and HTTPS

You can do DNS verification and enable automatic TLS certificates so easily in the HTTPS part of Domain management on the side bar (just need to click the button).

How should you write a new article

Create a new article

You just need the following commands to create a new article:

1
2
cd blog
hexo new post new_article_file_name

Then, you will find a new md file whose name is new_article_file_name in source -> _posts folder.

For the title of your article, you can set it on the top part of md file.

Note that:

  1. new_article_file_name is the Markdown file name, but not the title of your article.
  2. When you start writing Markdown file, the highest head should be head 2 not head 1 because you have set the title on the top part of md file.

Now you can edit the Markdown file to write the articles.

By the way, I use Typora + iPic (Image Upload Tool) + Imgur (Image hosting service) to write the blog (Mardown files). Here is also a perfect Markdown tutorial website.

Push the local repo to GitHub

Bash

You can use bash to push the repo to GitHub:

1
2
3
git add .
git commit -m ""
git push -u origin main

GitHub Desktop

You can also simply use GitHub Desktop to commit and push. You can edit the comments on the left-bottom corner and push on the top button:

How should you delete the articles

You can simply remove md files in source -> _posts folder. And push the local repo to GitHub again. Netlify will help you regenerate and deploy the blog site.

Tips

Insecure mixed content detected in

You may note that there is an alert of Netlify which said that Insecure mixed content detected in. The reason for that is the configuration file sets url as http and example.com.

So you need to modify the configuration file _config.yml of you blog.

1
2
3
# URL
## Set your site url here. For example, if you use GitHub Page, set url as 'https://username.github.io/project'
url: https://your_domain.com

Hexo + GitHub Pages

Because Netlify uses the build command hexo generate, we cannot use hexo generate and hexo deploy (which uses the deploy settings in _config.yml) to deploy the blog site on the repo whose name is yourname.github.io. That means Netlify is in conflict with hexo deploy on your local environment and also in conflict with the repo whose name is yourname.github.io.

If you want to deploy the blog site on GitHub Pages, you just need to set the deploy settings in _config.yml as in the section Configuration of Hexo. And then run hexo generate and hexo deploy on your local environment. GitHub will automatically deploy the blog site with GitHub Actions (although in actions workflow it say that it builds with Jekyll, it actually build with Hexo). You don’t need to git init local blog folder and connect to the GitHub repo because hexo deploy will only use the deploy settings in _config.yml and help you to push and deploy the blog site on GitHub.

Conclusion

Hexo + GitHub + Netlify is a very convenient combo for blog writing.

Enjoy the blogging!