A short tutorial on Hexo to writting blogs

This is a simple tutorial on Hexo, including how to use Hexo and deploy to GitHub pages. This also serves as a quick reference for the author.

Usages

Essential terminal commands

The following are essential commands to start and publish an article.

  • Create a new post: $ hexo new "My New Post"

  • Run server: $ hexo server or $ hexo s

  • Generate static files: $ hexo generate or $ hexo g

  • Deploy to remote sites: $ hexo deploy

Use org-mode to write blogs for Hexo

This workflow depends on a function written in init-orgmode.el and a few snippets for org-mode. After exporting markdown files into the _posts folder, the mentioned shortcuts are provided by hexo major mode. You may alternatively use terminal commands to generate and deploy blogs, if this major mode is not installed.

  1. Create an article using org-mode, in which, use the snippet hexo-head (trigger key: hexo) to create metadata for Hexo markdown, including “title”, “date”, “tags”, etc.

    • You could use hexo-more (key: more) to insert the line <!--more-->.

    • You could use the collection of snippets hexo-callout-* (key: callout) to insert Bootstrap callout environments.

  2. Once drafting is done, you then call zyue/hexo-ox-gfm to export the .md file into _posts/ under the blog home.

  3. Call zyue/hexo to start Hexo major mode. Use shortcuts s r to run the localhost to check the article and s s to stop the localhost. If everything is well documented, use s d to publish your article to the github page.

Note: The minor mode ox-gfm uses the github-favored markdown, which preserves soft line breaks. That implies, every line break in org-mode is preserved in markdown files. You may have to unfill-paragraph to avoid unnecessary line breaks in markdown.

Installation

This section mainly refers to How to use Hexo and deploy to GitHub Pages, which guides me to build up this blog site. All credits deserved by btfak.

Install Hexo

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
$ sudo npm install -g hexo-cli

$ hexo -v
hexo-cli: 1.0.4
os: Darwin 16.7.0 darwin x64
http_parser: 2.7.0
node: 7.7.2
v8: 5.5.372.41
uv: 1.11.0
zlib: 1.2.11
ares: 1.10.1-DEV
modules: 51
openssl: 1.0.2k
icu: 58.2
unicode: 9.0
cldr: 30.0.3
tz: 2016j

Create a project for your GitHub Pages

1
2
3
4
5
6
7
$ hexo init oracleyue.github.io
INFO Copying data to ~/***/oracleyue.github.io
INFO You are almost done! Don't forget to run 'npm install' before you start blogging with Hexo!

$ cd oracleyue.github.io

$ npm install

Set information for your new blog

Edit _config.yml and refer to the doc https://hexo.io/docs/configuration.html.

Set information to use Git

https://github.com/hexojs/hexo-deployer-git

1
2
3
4
5
6
7
8
9
10
$ npm install hexo-deployer-git --save
$ vi _config.yml

~~~~~~~~~~~~~~~~~~ _config.yml ~~~~~~~~~~~~~~~~~~
# Deployment
## Docs: http://hexo.io/docs/deployment.html
deploy:
type: git
repo: git@github.com:yt8yt/yt8yt.github.io.git
branch: master

Set “watch” before starting your work

“watch” command can monitor your files. https://hexo.io/docs/generating.html

1
$ hexo generate --watch

Deploy your new blog!!

https://hexo.io/docs/deployment.html

1
2
$ hexo clean
$ hexo deploy

After writting the above command, you can see your new blog on GitHub Pages.

Create a new page file

https://hexo.io/docs/writing.html

1
2
3
4
5
6
$ hexo new page aboutme
INFO Created: ~/***/***.github.io/source/aboutme/index.md

$ cd source/aboutme/

$ edit index.md

Add “read more” folding

Add <!-- more --> in the right place.

Plugins

https://github.com/hexojs/hexo/wiki/Plugins

List of plugins used:

  • hexo-deployer-git
  • hexo-generator-feed
  • hexo-math

Add RSS

First of all, install the plugin hexo-generator-feed (under your blog root path)

1
$ npm install hexo-generator-feed --save

which will generate a subfolder hexo-generator-feed under your HEXO/node_modules/.

Add the following settings in your hexo _config.yml:

1
2
3
4
5
6
7
8
plugin:
- hexo-generator-feed

# RSS feeds
feed:
type: atom
path: atom.xml
limit: 20

and the _config.yml of your theme:

1
rss: "/atom.xml"

LaTeX

We use hexo-math to render LaTeX sources. First of all, install the plugin

1
npm install hexo-math --save

Then set mathjax in your hexo _config.yml:

1
2
3
4
5
6
math:
engine: 'mathjax'
mathjax:
src: custom_mathjax_source
config:
# MathJax config

and remember to enable it in the _config.yml of your theme, e.g. hexo-theme-next:

1
2
3
4
5
math:
enable: true
per_page: false

engine: mathjax

Note: if set per_page: true, you have to specify mathjax: true in the font matter of each markdown files.

The following is a test of LaTeX codes: the $\LaTeX$ equation for $u_i(x,t)$: $$ \frac{\partial u_i}{\partial t} = \lambda \frac{\partial^2 u_i}{\partial x^2}. $$

Code highlight

The following is an example of Python codes:

1
2
3
4
5
6
7
8
9
favorite_languages = {
'jen': 'python',
'sarah': 'c',
'edward': 'ruby',
'phil': 'python',
}
for name, language in favorite_languages.items():
print(name.title() + "'s favorite language is " +
language.title() + ".")

Support for Chinese

It works out of box. Here should be a sentence in Chinese: 这里应该有一段中文。