Hexo and GitHub

KaTeX is the fastest math typesetting library for the web. Hexo is a fast, simple & powerful blog framework. KaTeX, Hexo and GitHub together is a good choice for those who want to build a Blog and write some equations on his/her posts. Before embed KaTeX, let’s build Hexo on GitHub.

1. Hexo

Requirements

Node.js
Git
More info: hexo doc

Install Hexo

In your terminal

1	$ npm install hexo-cli -g

If it doesn’t work on your Mac, try adding sudo at the beginning.

Setup your blog

1 2	$ hexo init MyBlog $ cd MyBlog

A directory MyBlog is created and initialized. It’s the Hexo root directory where your hexo files are stored.

Run local server

1	$ hexo server

The output is:

1 2	INFO Start processing INFO Hexo is running at http://localhost:4000 . Press Ctrl+C to stop.

Open http://localhost:4000 in your brower, you’ll see your initial site.

More info: hexo.io, hexo-github

2. Deploy to GitHub

2.1 Create an empty repository

If you don’t have a GitHub account, create one. If you have a GitHub account, click https://github.com/new and create a empty repository: Choose a name(say ‘MyBlog’), and click create repository, leave everything else alone. Click “Create repository”. Look at your browser, the url of your repository is

1	https://github.com/YOUR-GITHUB-ACCOUNT/YOUR-REPOSITORY

2.2 Deploy your site

Install hexo-deployer-git

1	$ npm install hexo-deployer-git --save

Once installed, find a file _config.yml in MyBlog, the Hexo root directory. Edit the following
part:

url: https://YOUR-GITHUB-ACCOUNT.github.io/YOUR-REPOSITORY/  # This is your site url.
root: /YOUR-REPOSITORY/
...
...
deploy:
  type: git
  repo: https://github.com/YOUR-GITHUB-ACCOUNT/YOUR-REPOSITORY  # This is your repository url.
  branch: master

If you use text editor such as Atom or Sublime, don’t forgget to save your changes. If you do not have Atom or Sublime, you may use command

1	$ vi _config.yml

After edittig, press ‘Esc’ and input :wq to save the changes. Then

1	$ hexo clean && hexo deploy

Sometimes you need to generate categories and tags files before deployment(See the bottom of this post):

1	$ hexo clean && hexo deploy -g

Go back to your browser, refresh your GitHub repository page, find Settings button and click it. Scroll down to the tag “GitHub Pages”, now your “Source” is None. Click None button, select master branch and Save. After your site automatically refreshed. Go back to the tag “GitHub Pages”, you’ll see

1	Your site is published at https://YOUR-GITHUB-ACCOUNT.github.io/YOUR-REPOSITORY/

Click the link and you will see a “404” error message. Don’t panic, refresh your brower several minutes later and you’ll see a “Hello World” post on your site.
More info: hexo doc.

2.3 Create another repository for your Hexo develpment files

There is a vital difference between Hexo and Jekyll. In Jekyll, develpment files and site files are pushed to the same repository on GitHub. In Hexo, if you want to keep track of your develpment, you need to create another repository on GitHub.
Let’s create one and call it YOUR-DEV-REPOSITORY.

The following operations are on
https://github.com/YOUR-GITHUB-ACCOUNT/YOUR-DEV-REPOSITORY # Your dev repository
not
https://github.com/YOUR-GITHUB-ACCOUNT/YOUR-REPOSITORY # Your site repository
or
https://YOUR-GITHUB-ACCOUNT.github.io/YOUR-REPOSITORY/ # Your site

Another tip: Before you do anything BIG, backup your local Hexo root repository and save it somewhere else. Just in case.

2.4 Push develpment files to GitHub

Go back to your terminal, change directory to your Hexo root directory(in my case it’s MyBlog).

$ git init
$ git status
$ git add .
$ git commit -m "first commit"
$ git remote add origin https://github.com/YOUR-GITHUB-ACCOUNT/YOUR-DEV-REPOSITORY.git
$ git push origin master

Refresh YOUR-DEV-REPOSITORY on GitHub, if there are folders like scaffolds, source, themes etc, your develpment are uploaded. There are two things need to mention.

Alias for a link

Line 5 means you give your link a alias “origin”. So if you want to push a branch to it, you don’t need to copy and paste this link like this:

1	$ git push https://github.com/YOUR-GITHUB-ACCOUNT/YOUR-REPOSITORY.git master

You may choose another alias if you want. For example:

1 2	$ git remote add destination https://github.com/YOUR-GITHUB-ACCOUNT/YOUR-REPOSITORY.git $ git push destination master

“origin” is just the default alias.
Other usefull commands:

1 2	$ git remote -v // List all aliases. $ git remote rm destination // Remove the alias named "destination".

master vs. gh-pages

If you want to create a repository on branch “gh-pages” instead of “master”, add one line after git init and replace master with gh-pages, it looks like this:

$ git init
$ git checkout -b gh-pages
$ git status
$ git add .
$ git commit -m "first commit"
$ git remote add origin https://github.com/YOUR-GITHUB-ACCOUNT/YOUR-REPOSITORY.git
$ git push origin gh-pages

Both works fine. I prefer “master”, the default one.
More info: branch, git doc

One more thing

If you are asked to create a submodule, do it. This means you will create new repository to backup your personalized theme. Three steps.
Step 1, Fork the origial theme NexT.
Go to hexo-theme-next and click “Fork”.
Go back to your own GitHub directories, a new reopository “hexo-theme-next” is there.
Step 2, Connect your local theme to GitHub
In your local Hexo root directory, change to themes/next:

$ cd themes/next
$ ls
LICENSE.md      bower.json      gulpfile.coffee package.json    test
README.md       crowdin.yml     languages       scripts
_config.yml     docs            layout          source

Make sure your working directory is “next”. Then

$ git status
$ git add .
$ git commit -m "update theme"
$ git remote add theme https://github.com/YOUR-GITHUB-ACCOUNT/hexo-theme-next
$ git push theme master

If you are asked to pull,

1	$ git pull

If you are asked to merge,

1 2	$ git merge "please enter a commit message to explain why this merge is necessary, especially if it merges an updated upstream into a topic branch."

press “i”
input your merge message
press “esc”
write “:wq”
then press enter

Check your GitHub repository “hexo-theme-next” and see “Latest commit … seconds ago”.
Step 3, connect your submodule to this directory.

1	$ git submodule add https://github.com/YOUR-GITHUB-ACCOUNT/hexo-theme-next.git themes/next

In your Hexo root directory, you will find a file .gitmodules. Open it, it should like this:

1
2
3

[submodule "themes/next"]
	path = themes/next
	url = https://github.com/YOUR-GITHUB-ACCOUNT/hexo-theme-next.git

More info: Git doc, merge message(you may need it), ref

3. Check everything

Sever, Deploy and Push

Run local server

Go back to Hexo root directory and run local server

$ cd ..
$ cd ..
$ ls
_config.yml             package-lock.json       scaffolds
db.json                 package.json            source
node_modules            public                  themes
$ hexo server

Open http://localhost:4000 in a brower. The site is there.

Write a new post

1	$ hexo new "New Post"

Refresh browser. “New Post” is there.

Generate and Deploy

Stop the local server(Ctrl+C), and

1	$ hexo clean && hexo deploy -g

Open https://YOUR-GITHUB-ACCOUNT.github.io/YOUR-REPOSITORY/ in a browser. “New Post” is there.

Push to GitHub

$ git status
$ git add .
$ git commit -m "Dev files updated"
$ git push origin master

Refresh YOUR-DEV-REPOSITORY on GitHub and see Latest commit ... seconds ago.
If everything works fine, we are good to go.
More info: Git & GitHub Tutorial for Beginners