Hexo

Hexo

[TOC]

本文为 Hexo 官网的使用手册整理以及个人使用过程中的总结.

个人总结

手册当中虽然没有直接总结出来, 但是有些概念对于新手而言是非常重要的. 这里我粗浅地总结如下, 毕竟不是搞网页, 前端的, 认知水平有限, 欢迎指正.

关于 Hexo 的一些概念

何为 layout(布局), page, post 以及 draft?

  • 布局可以理解为模板, 网页上各个元素的组织与呈现, 例如文字位置, 边框位置, 字体, 色彩等, 我们每一篇文章/页面都重头来的话, 太浪费时间, 可以在创建文章/页面的时候指定总结的模板节约时间.

  • page 为非文章的其余网页, 例如首页, 标签页, 存档页等, 它们显示的东西不是文章.

  • post 为文章也就是每个 markdown 文件最后生成对应的东西.

  • draft 为文章的草稿, 新建的文章确定修改好需要发布, 执行 publish 命令即可把它们移动到 _post 文件夹下, 生成网页.

其他的概念很容易懂.

  • resource/data 为一篇文章中需要的多媒体资源, 例如图片, 特殊的渲染脚本等. 对于这些资源, 最关键的是如何使文本的文章 .md 文件找到它们. 这也就涉及到了路径问题.

何为文章标题, 文件名, 文章名?

  • 文章标题为 front-matter(.md 文件最头部位置的一种标签格式, 后文展开)中的 title 字段对应的值, 在实际网页呈现中为一篇文章的标题.
  • 文件名为 markdown 等文章文本文件 .md 前面的部分. 在生成网页永久链接的时候使用 name 字段. 这个字段是路径无关的, 也就是说只要放在 source/_posts/ 下不管有多少层子目录都可以截取处文件名. 我建议文件名全部使用英文/拼音, 因为生成网页链接的时候汉字会被转换成不好懂的字符串, 不利于管理以及记忆.
  • 文章名, 可以理解为路径字符串的截取, source/_posts/ 路径开始到 .md 之间的部分, 即与文件名相比增加了相对路径信息.

这部分区别在永久链接生成的部分会再次提到.

Hexo 下的工作流

  • Hexo 下的文件流如下:

draft(.md + resource) -> post -> public -> remote.

  • Hexo 系统的工作流:
    写文章(.md + Image 等) -> 通过 CSS 文件渲染生成 html 文件(或者依赖的其他文件) -> 推送到网页端, 辅助利用网页浏览器的渲染功能实现最终文章的呈现.

这里的推送可以是本地虚拟的网页端, 通过 hexo -s 实现, 也可以是推送到远程服务器, 通过 IP/网址 访问.

渲染也分为了本地端(server)的渲染以及网页浏览器(brower)的渲染, 建议主要依赖前者, 虽然前者更消耗服务器端渲染的资源, 但是效果更可靠.

渲染中涉及到对文本文件的解析, .md 文件中最简便的便是 markdown 的语法, 但我们知道我们可以使用 html 的标签实现同样的效果(虽然麻烦一些, 但有些时候 markdown 不支持的地方也不得不用 html 标签). 除了这两种语法, Hexo 还默认支持 tag plugin 这种标签语言, 具体的规则在后面的手册整理部分有介绍. 这三种默认支持的语法的解析优先级如下:
html > tag plugin > markdown.

当然并不是绝对的, 例如 markdwon 里的 <u><\u> 标签就无法被解析出来.

同时如果安装了 Hexo 的一些插件, 其他一些标签语法也是支持的, 本文不做介绍.

配置文件的优先级

后面会重复列出, 但考虑到 Hexo 严重依赖于配置文件, 这里列在比较开头的位置.

Hexo 默认的配置文件 _config.yml 中的 theme_config 的优先级最高,其次是 _config.[theme].yml 文件,最后是位于主题目录下的 _config.yml 文件.

安装

安装前提

  • Node.js(12.0 及以上版本)
  • Git

安装 Hexo

1
npm install -g hexo-cli

进阶安装和使用

局部安装 hexo 包

1
npm install hexo

两种方式执行 Hexo:

  1. npx hexo <command>
  2. 将 Hexo 所在的目录下的 node_modules 添加到环境变量之中即可直接使用 hexo <command>
    1
    echo 'PATH="$PATH:./node_modules/.bin"' >> ~/.profile

Node.js 版本限制

官方强烈建议永远安装最新版本的 Hexo,以及推荐的 Node.js 版本, 对应关系如下:

Hexo 版本 最低兼容 Node.js 版本
6.0+ 12.13.0
5.0+ 10.13.0
4.1 - 4.2 8.10
4.0 8.6
3.3 - 3.9 6.9
3.2 - 3.3 0.12
3.0 - 3.1 0.10 or iojs
0.0.1 - 2.8 0.10

建站

安装 Hexo 完成后,请执行下列命令,Hexo 将会在指定文件夹中新建所需要的文件.

1
2
3
hexo init <folder>
cd <folder>
npm install

新建完成后,指定文件夹的目录如下:

1
2
3
4
5
6
7
8
9
.
├── _config.yml #网站的配置信息
├── package.json #应用程序/插件的信息,用来管理插件.
├── scaffolds #模版文件夹.新建文章时,Hexo 会根据 scaffold 来建立文件.
├── source #存放用户资源的地方,除 _posts 文件夹之外,开头命名为 _ (下划线)的文件 / 文件夹和隐藏的文件将会被忽略.
| ├── _drafts # 草稿
| └── _posts # 博文及其资源
| └── _data # 一些公用的资源
└── themes #Hexo 会根据主题来生成静态页面.

配置

_config.yml中, 汇总简介如下, 很多一看之下可能无法理解, 后面会逐个解释.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
#                   #
## 网站 ##
# #
title: Challenging-eXtraordinary #主页标题
subtitle: ' ' #副标题
description: ' ' # 网站描述,主要用于SEO(Search Engine Optimization),告诉搜索引擎一个关于站点的简单描述
keywords: null
author: #作者,左下角显示
language: zh-CN # 选择中文简体, 还有 zh-Hans
timezone: 'Asia/Shanghai' # 网站时区。Hexo 默认使用电脑的时区。
# #
## 网址 ##
# #
url: http://www.chuxin911.com # 必须以 http:// 或 https:// 开头
root: / # 网站根目录
permalink: ':name_:year:month:day/' # 文章的永久链接格式
permalink_defaults: null #永久链接中各部分的默认值
pretty_urls: #改写 permalink 的值来美化 URL
trailing_index: false #是否在永久链接中保留尾部的index.html,设置为false时去除
trailing_html: true #是否在永久链接中保留尾部的.html, 设置为false时去除 (对尾部的index.html无效)
# #
## 目录 ##
# #
source_dir: source #资源文件夹,这个文件夹用来存放内容
public_dir: public #公共文件夹,这个文件夹用于存放生成的站点文件
tag_dir: tags #标签文件夹
archive_dir: archives #归档文件夹
category_dir: categories #分类文件夹
code_dir: downloads/code #Include code 文件夹,source_dir 下的子目录
i18n_dir: ':lang' #国际化(i18n)文件夹,是 internationalization 单词的简写,中间18个字符略去,简称 i18n,意图就是同一个网站可以支持多种不同的语言
skip_render: null #跳过指定文件的渲染。匹配到的文件将会被不做改动地复制到 public 目录中。可使用 glob 表达式来匹配路径。
# #
## 文章 ##
# #
menu:
about: 关于
new_post_name: ':title.md' #新文章的文件名称
default_layout: post #预设布局
auto_spacing: true #在中文和英文之间加入空格
titlecase: false #把标题转换为 title case
external_link:
enable: true #在新标签中打开链接
field: site #对整个网站(site)生效或仅对文章(post)生效
exclude: '' #需要排除的域名。主域名和子域名如 www 需分别配置
filename_case: 0 #把文件名称转换为 (1) 小写或 (2) 大写
render_drafts: false #显示草稿
post_asset_folder: true #启动Asset文件夹.Asset代表source文件夹中除了文章以外的所有文件,例如图片、CSS、JS 文件等。比方说,如果你的Hexo项目中只有少量图片,那最简单的方法就是将它们放在 source/images 文件夹中。然后通过类似于 ![](/images/image.jpg) 的方法访问它们。
relative_link: false #把链接改为与根目录的相对位址
future: true #显示未来时间点的文章
highlight: #代码块的设置, 请参考 Highlight.js 进行设置
enable: true
line_number: true
auto_detect: false
tab_replace: ''
wrap: true
hljs: false
prismjs: #代码块的设置, 请参考 PrismJS 进行设置
enable: false
preprocess: true
line_number: true
tab_replace: ''
index_generator:
path: ''
per_page: 10
order_by: '-date'
# #
## 分类 & 标签 ##
# #
default_category: uncategorized #默认分类
category_map: null #分类别名
tag_map: null #标签别名
# #
## 日期 / 时间格式 ##
# #
meta_generator: true #Meta generator标签。 值为false时Hexo不会在头部插入该标签
date_format: YYYY-MM-DD #Hexo 使用 Moment.js 来解析和显示时间
time_format: HH:mm:ss
updated_option: mtime #当Front Matter中没有指定updated时updated的取值. 选项如下:
#mtime: 使用文件的最后修改时间.
#date: 使用date作为updated的值.可被用于Git工作流之中,因为使用Git管理站点时,文件的最后修改日期常常会发生改变.
#empty: 直接删除updated,使用这一选项可能会导致大部分主题和插件无法正常工作.
# #
## 分页 ##
# #
per_page: 10 # 每页显示的文章量 (0 = 关闭分页功能)
pagination_dir: page #分页目录
# #
## 扩展 ##
# #
include: null #在 Hexo 配置文件中,通过设置 include/exclude 可以让 Hexo 进行处理或忽略某些目录和文件夹。可以使用 glob 表达式 对目录和文件进行匹配。
#include 和 exclude 并不适用于 themes/ 目录下的文件。如果需要忽略 themes/ 目录下的部分文件或文件夹,可以使用ignore或在文件名之前添加下划线_
exclude: null
ignore: null
theme: icarus #当前主题名称。值为false时禁用主题
theme_config: null #主题的配置文件。在这里放置的配置会覆盖主题目录下的 _config.yml 中的配置
deploy: #部署部分的设置
type: git
repo: root@139.224.210.242:/home/git/MyBlog.git
branch: master
message: null

网站存放在子目录

如果您的网站存放在子目录中,例如 http://example.com/blog,则请将您的 url 设为 http://example.com/blog 并把 root 设为 /blog/.

写作

执行下列命令来创建一篇新文章或者新的页面.

1
hexo new [layout] <title>

可以在命令中指定文章的布局(layout),默认为 post,可以通过修改 _config.yml 中的 default_layout 参数来指定默认布局.

布局(Layout)

Hexo 有三种官方默认布局:post,page 和 draft .在创建这三种不同类型的文件时,它们将会被保存到不同的路径下.分别如下:

布局 路径
post source/_posts
page source
draft source/_drafts

自定义的的布局和 post 相同,都将储存到 source/_posts 文件夹.

Disabling layout

set layout: false in its front-matter.

文件名称

Hexo 默认以标题做为文件名称,但也可编辑 new_post_name 参数来改变默认的文件名称,举例来说,设为 :year-:month-:day-:title.md 可让您更方便的通过日期来管理文章.

变量 描述
:title 标题(小写,空格将会被替换为短杠)
:year 建立的年份,比如, 2015
:month 建立的月份(有前导零),比如, 04
:i_month 建立的月份(无前导零),比如, 4
:day 建立的日期(有前导零),比如, 07
:i_day 建立的日期(无前导零),比如, 7

草稿

可通过 publish 命令将草稿移动到 source/_posts 文件夹.

1
hexo publish [layout] <title>

草稿默认不会显示在页面中,可在执行时加上 --draft 参数,或是把 render_drafts 参数设为 true 来预览草稿.

扩展

includeexclude 选项

在 Hexo 配置文件中,通过设置 include/exclude 可以让 Hexo 进行处理或忽略某些目录和文件夹.你可以使用 glob 表达式 对目录和文件进行匹配.

includeexclude 选项只会应用到 source/ ,而 ignore 选项会应用到所有文件夹.

参数 描述
include Hexo 默认会不包括 source/ 下的隐藏类文件和文件夹
(包括名称以下划线和 . 开头的文件和文件夹,Hexo 的 _posts_data 等目录除外).
通过设置此字段将使 Hexo 处理他们并将它们复制到 source 目录下.
exclude Hexo 不包括 source/ 下的这些文件和目录
ignore Hexo 会忽略整个 Hexo 项目下的这些文件夹或文件

举例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# 处理或不处理目录或文件
include:
- ".nojekyll"
# 处理 'source/css/_typing.css'
- "css/_typing.css"
# 处理 'source/_css/' 中的任何文件,但不包括子目录及其其中的文件.
- "_css/*"
# 处理 'source/_css/' 中的任何文件和子目录下的任何文件
- "_css/**/*"

exclude:
# 不处理 'source/js/test.js'
- "js/test.js"
# 不处理 'source/js/' 中的文件,但包括子目录下的所有目录和文件
- "js/*"
# 不处理 'source/js/' 中的文件和子目录下的任何文件
- "js/**/*"
# 不处理 'source/js/' 目录下的所有文件名以 'test' 开头的文件,但包括其它文件和子目录下的单文件
- "js/test*"
# 不处理 'source/js/' 及其子目录中任何以 'test' 开头的文件
- "js/**/test*"
# 不要用 exclude 来忽略 'source/_posts/' 中的文件.你应该使用 'skip_render',或者在要忽略的文件的文件名之前加一个下划线 '_'
# 在这里配置一个 - "_posts/hello-world.md" 是没有用的.

ignore:
# 忽略任何一个名叫 'foo' 的文件夹
- "**/foo"
# 只忽略 'themes/' 下的 'foo' 文件夹
- "**/themes/*/foo"
# 对 'themes/' 目录下的每个文件夹中忽略名叫 'foo' 的子文件夹
- "**/themes/**/foo"

列表中的每一项都必须用单引号或双引号包裹起来.

includeexclude 并不适用于 themes/ 目录下的文件.如果需要忽略 themes/ 目录下的部分文件或文件夹,可以使用 ignore 或在文件名之前添加下划线 _.

使用代替配置文件

hexo-cli 中使用 --config 参数来指定自定义配置文件的路径,支持 YAML 或 JSON 文件格式. 可以使用一个配置文件的路径,也可以使用逗号分隔(无空格)的多个配置文件的路径.例如:

1
2
3
4
5
# 用 'custom.yml' 代替 '_config.yml'
$ hexo server --config custom.yml

# 使用 'custom.yml' 和 'custom2.json',优先使用 'custom3.yml',然后是 'custom2.json'
$ hexo generate --config custom.yml,custom2.json,custom3.yml

当你指定了多个配置文件以后,Hexo 会按顺序将这部分配置文件合并成一个 _multiconfig.yml.如果遇到重复的配置,排在后面的文件的配置会覆盖排在前面的文件的配置.这个原则适用于任意数量,任意深度的 YAML 和 JSON 文件.

例如:

1
$ hexo generate --config custom.yml,custom2.json

如果 custom.yml 中指定了 foo: bar,在 custom2.json 中指定了 "foo": "dinosaur",那么在 _multiconfig.yml 中你会得到 foo: dinosaur.

使用代替主题配置文件

优先级:

Hexo 在合并主题配置时,Hexo 配置文件 _config.yml 中的 theme_config 的优先级最高,其次是 _config.[theme].yml 文件,最后是位于主题目录下的 _config.yml 文件.

下面进行展开:

配置文件中的 theme_config

该特性自 Hexo 2.8.2 起提供.

例如:

1
2
3
4
5
6
7
8
9
10
11
# _config.yml
theme: "my-theme"
theme_config:
bio: "My awesome bio"
foo:
bar: 'a'
# themes/my-theme/_config.yml
bio: "Some generic bio"
logo: "a-cool-image.png"
foo:
baz: 'b'

最终主题配置的输出是:

1
2
3
4
5
6
7
8
{
bio: "My awesome bio",
logo: "a-cool-image.png",
foo: {
bar: "a",
baz: "b"
}
}

独立的 _config.[theme].yml 文件

该特性自 Hexo 5.0.0 起提供.

独立的主题配置文件应放置于站点根目录下,支持 ymljson 格式.需要配置站点 _config.yml 文件中的 theme 以供 Hexo 寻找 _config.[theme].yml 文件.

1
2
3
4
5
6
7
8
9
10
11
# _config.yml
theme: "my-theme"
# _config.my-theme.yml
bio: "My awesome bio"
foo:
bar: 'a'
# themes/my-theme/_config.yml
bio: "Some generic bio"
logo: "a-cool-image.png"
foo:
baz: 'b'

最终主题配置的输出是:

1
2
3
4
5
6
7
8
{
bio: "My awesome bio",
logo: "a-cool-image.png",
foo: {
bar: "a",
baz: "b"
}
}

强烈建议你将所有的主题配置集中在一处.

文章模版(Scaffold)

1
hexo new photo "My Gallery"

在执行这行指令时,Hexo 会尝试在 scaffolds 文件夹中寻找 photo.md,并根据其内容建立文章,以下是您可以在模版中使用的变量:

变量 描述
layout 布局
title 标题
date 文件建立日期

支持的格式

Hexo 支持以任何格式书写文章,只要安装了相应的渲染插件.

例如,Hexo 默认安装了 hexo-renderer-markedhexo-renderer-ejs,因此你不仅可以用 Markdown 写作,你还可以用 EJS 写作.如果你安装了 hexo-renderer-pug,你甚至可以用 Pug 模板语言书写文章.

只需要将文章的扩展名从 md 改成 ejs,Hexo 就会使用 hexo-renderer-ejs 渲染这个文件,其他格式同理.

Front-matter

文件最上方以 --- 分隔的区域,用于指定个别文件的变量.

例如:

1
2
3
4
---
title: Hello World
date: 2013/7/13 20:46:25
---

一些预先定义的参数,可在模板中使用这些参数值.

参数 描述 默认值/用法
layout 布局 _config.yml default_layout参数
title 标题 文章的文件名
date 建立日期 文件建立日期
updated 更新日期 文件更新日期
comments 开启文章的评论功能 true
tags 标签(不适用于分页)
categories 分类(不适用于分页)
permalink 覆盖文章网址
excerpt 文章摘要 <!-- more --> before plain text
disableNunjucks Disable rendering of Nunjucks tag
and tag plugins.
lang _config.yml

分类和标签

Hexo 中两者有着明显的差别:分类具有顺序性和层次性,而标签没有顺序和层次.

1
2
3
4
5
6
categories:
- Blog
- Diary
tags:
- PS3
- Games

该文章属于 Blog 大类, Diary 小类, 标签为 PS3 以及 Games.

Hexo 不支持指定多个同级分类( WordPress 支持).

如果你需要为文章添加多个分类,可以尝试以下 list 中的方法.

1
2
3
4
categories:
- [Diary, PlayStation]
- [Diary, Games]
- [Life]

此时这篇文章同时包括三个分类: PlayStationGames 分别都是父分类 Diary 的子分类,同时 Life 是一个没有子分类的分类.

JSON Front-matter

除了 YAML 外,你也可以使用 JSON 来编写 Front-matter,只要将 --- 代换成 ;;; 即可.

1
2
3
"title": "Hello World",
"date": "2013/7/13 20:46:25"
;;;

Hexo 生成的超链接

默认情况下,Hexo 生成的超链接都是绝对地址.例如,如果您的网站域名为 example.com,您有一篇文章名为 hello,那么绝对链接可能像这样:http://example.com/hello.html,它是绝对于域名的.相对链接像这样:/hello.html,也就是说,无论用什么域名访问该站点,都没有关系,这在进行反向代理时可能用到.通常情况下,建议使用绝对地址.

资源文件夹

资源(Asset)代表 source 文件夹中除了文章以外的所有文件,例如图片,CSS,JS 文件等.

有 3 种方式可以用来管理资源:

  1. 放到 source 文件夹下进行管理, 并通过 markdonw 的 ![]() 语法进行引用. 例如: 图片放入 source/images 中, 文章使用 ![](/images/image.jpg) 的形式进行引用.

  2. 通过文章分门别类管理资源: 首先 config.yml 文件中的 post_asset_folder 选项设为 true 来打开此功能. 然后 Hexo 将会在你每一次通过 hexo new [layout] <title> 命令创建新文章时自动创建一个文件夹.这个资源文件夹将会有与这个文章文件一样的名字.将所有与你的文章有关的资源放在这个关联文件夹中之后,你可以通过相对路径来引用它们.

  3. 通过常规的 markdown 语法和相对路径来引用图片和其它资源可能会导致它们在存档页或者主页上显示不正确.应该使用如下方法进行引用,例如 {% asset_img example.jpg This is an example image %}:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
       {% asset_path slug %}
    {% asset_img slug [title] %}
    {% asset_link slug [title] %}

    如果安装了[hexo-renderer-marked](https://github.com/hexojs/hexo-renderer-marked) 3.1.0 以上版本插件并开启之, 可以使用常规的 markdown 语法, 并会自动解析资源的路径.

    ```yaml
    _config.yml
    post_asset_folder: true
    marked:
    prependRoot: true
    postAsset: true

可以在 _config.yml 配置中调整网站的永久链接或者在每篇文章的 Front-matter 中指定.注意永久链接的变动可能会影响 SEO.

例如: _config.ymlpermalink_defaults 参数下调整永久链接中各变量的默认值:

1
2
permalink_defaults:
lang: en

变量

除了下列变量外,您还可使用 Front-matter 中的所有属性.

变量 描述
:year 2012
:month 02
:i_month 2
:day 01
:i_day 1
:hour 02
:minute 05
:second 09
:title 文件名称 (relative to “source/_posts/“ folder)
:name 文件名称
:post_title 文章标题
:id 文章 ID(not persistent across cache reset)
after hexo clean
:category 分类.如果文章没有分类,
则是_config.yml
default_category 配置信息.
:hash SHA1 hash of filename (same as :title)
and date (12-hexadecimal)

示例:

source/_posts/hello-world.md

1
2
3
4
5
title: Hello Worl
ddate: 2013-07-14 17:01:34
categories:
- foo
- bar
参数 结果
:year/:month/:day/:title/ 2013/07/14/hello-world/
:year-:month-:day-:title.html 2013-07-14-hello-world.html
:category/:title/ foo/bar/hello-world/
:title-:hash/ hello-world-a2c8ac003b43/

source/_posts/lorem/hello-world.md

1
2
3
4
5
title: Hello World2
date: 2013-07-14 17:01:34
categories:
- foo
- bar
参数 结果
:year/:month/:day/:title/ 2013/07/14/lorem/hello-world/
:year/:month/:day/:name/ 2013/07/14/hello-world/
:year/:month/:day/:post_title/ 2013/07/14/hello-world2/

这里备注一下 :title, :name, :post_title 的区别:

  • :title : 可以理解为路径字符串的截取, source/_posts/路径开始到 .md 之间的部分.
  • :name: .md 文件的文件名, 不管其放在 source/_posts/ 的哪个子目录下.
  • :post_title: 这是 .md 文件里的 front matter 中的 post 字段的值.

可以看到这三个参数是逐步细化的层次关系.

需要注意的是, 不管是哪一个参数都会遵循_config.yml 配置文件中的 titlecase 或者 filename_case 大小写以及空格处理的规则.

多语种支持

若要建立一个多语种的网站,您可修改 new_post_namepermalink 参数,如下:

1
2
new_post_name: :lang/:title.md
permalink: :lang/:title/

当您建立新文章时,文章会被储存到:

1
2
hexo new "Hello World" --lang tw
# => source/_posts/tw/Hello-World.md

而网址会是:

1
http://localhost:4000/tw/hello-world/

Syntax Highlighting

Hexo 有2个内置的 syntax highlight 库, highlight.js and prismjs.

代码段的三种格式

Tag Plugin - Code Block

1
2
3
{% codeblock [title] [lang:language] [url] [link text] [additional options] %}
code snippet
{% endcodeblock %}

Tag Plugin - Backtick Code Block:

1
2
3
{% code [title] [lang:language] [url] [link text] [additional options] %}
code snippet
{% endcode %}

Markdown:

1
2
3
``` [language] [title] [url] [link text] [additional options]
code snippet
```

Hexo 支持 ejs, swig, nunjucks, pug, asciidoc, etc 格式, 只要安装了相应的 renderer plugin.

配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# _config.yml
highlight:
enable: true
auto_detect: false
line_number: true
line_threshold: 0
tab_replace: ''
exclude_languages:
- example
wrap: true
hljs: false
prismjs:
enable: false
preprocess: true
line_number: true
line_threshold: 0
tab_replace: ''

如果两个渲染插件都被 disable, 那么会使用默认的渲染器, 例如 hexo-renderer-marked , 然后转换为 html 的 <code> 标签.

1
2
3
```yaml
hello: hexo
```
1
2
3
<pre>
<code class="yaml">hello: hexo</code>
</pre>

如果没有 enable 内置的 syntax highlight 可以选择安装第三方插件, 如上面的 hexo-renderer-marked 或者考虑依赖浏览器端的 browser-side syntax hilighter.

Highlight.js 配置详解

highlight.js 默认 enabled.

server-side highlighting VS browser-side highlighting:

前者意味着语法高亮发生在 hexo generate or hexo server 期间.

auto_detect

highlight.js 会自动探测语言种类, 这在 “sublanguage highlight” (代码块中有子语言) 功能上很有用, 你只需要 enable 这个功能, 不需要指明语言种类也可以.

Warning: 此功能很耗资源, 除非真的必要, 不要轻易使用.

line_number

highlight.js 虽然不支持行号, 但是 Hexo 对其进行了包装实现了行号功能.

line_threshold (+6.1.0)

只有行数超过了 threashold 才会显示行号.

tab_replace

把 tab 换成 2 个 spaces

exclude_languages (+6.1.0)

只有被 <pre><code class="lang"></code></pre> 标签包装的时候此功能才其作用.

wrap

line_number 的开启依赖于此选项. 实现的功能是 Hexo wraps the output inside <figure> and <table> to support line number. 只有同时把 line_number 与 wrap 关掉, 才会关闭此行为.

hljs

这是使用 highlight.js 其他更多渲染功能的开关.

When line_number is set to false, wrap is set to false and hljs is set to true, you can then use highlight.js theme directly in your site.

PrismJS 配置详解

默认不开启

preprocess

browser-side (preprocess set to false)

server-side (preprocess set to true).

Prismjs is designed to be used in browser, thus under preprocess mode only limited prismjs plugin is supported:

  • Line Numbers

  • Show Languages

  • Any other prism plugins that don’t need special HTML markup

其余不展开感觉 highlight.js 就够用了.

指令

init

1
hexo init [folder]

新建一个网站.如果没有设置 folder ,Hexo 默认在目前的文件夹建立网站.

本命令相当于执行了以下几步:

  1. Git clone hexo-starterhexo-theme-landscape 主题到当前目录或指定目录.
  2. 使用 Yarn 1,pnpmnpm 包管理器下载依赖(如有已安装多个,则列在前面的优先).npm 默认随 Node.js 安装.

new

1
hexo new [layout] <title>

新建一篇文章.如果没有设置 layout 的话,默认使用 _config.yml 中的 default_layout 参数代替.如果标题包含空格的话,请使用引号括起来.

参数 描述
-p, –path 自定义新文章的路径
-r, –replace 如果存在同名文章,将其替换
-s, –slug 文章的 Slug,作为新文章的文件名和发布后的 URL

默认情况下,Hexo 会使用文章的标题来决定文章文件的路径.对于独立页面来说,Hexo 会创建一个以标题为名字的目录,并在目录中放置一个 index.md 文件.你可以使用 --path 参数来覆盖上述行为,自行决定文件的目录:

1
hexo new page --path about/me "About me"

以上命令会创建一个 source/about/me.md 文件,同时 Front Matter 中的 title 为 "About me"

注意!title 是必须指定的!如果你这么做并不能达到你的目的:

1
hexo new page --path about/me

此时 Hexo 会创建 source/_posts/about/me.md,同时 me.md 的 Front Matter 中的 title 为 "page".这是因为在上述命令中,hexo-cli 将 page 视为指定文章的标题,并采用默认的 layout.

generate

1
2
3
4
hexo generate
hexo g #简写
hexo g -d # hexo generate --deploy 与下面等效
hexo d -g # hexo deploy --generate
选项 描述
-d, –deploy 文件生成后立即部署网站
-w, –watch 监视文件变动
-b, –bail 生成过程中如果发生任何未处理的异常则抛出异常
-f, –force 强制重新生成文件
Hexo 引入了差分机制,如果 public 目录存在,那么 hexo g 只会重新生成改动的文件.
使用该参数的效果接近 hexo clean && hexo generate
-c, –concurrency 最大同时生成文件的数量,默认无限制

publish

1
hexo publish [layout] <filename>

发表草稿.

server

1
hexo server

启动服务器.默认情况下,访问网址为: http://localhost:4000/.

选项 描述
-p, –port 重设端口
-s, –static 只使用静态文件
-l, –log 启动日记记录,使用覆盖记录格式
-i 覆盖默认的 IP 0.0.0.0, 例如 hexo server -i 192.168.1.1
对于有公网IP的主机,如果您指定一个局域网IP作为-i参数的值,
那么就无法通过公网来访问站点.

Mac 系统上使用 Pow (零配置 Rack 服务器),作为一个简单易用的静态文件服务器来使用.

deploy

1
2
hexo deploy
hexo d #简写

部署网站.-g, --generate部署之前预先生成静态文件.

render

1
hexo render <file1> [file2] ...

渲染文件. -o, --output 设置输出路径.

migrate

1
hexo migrate <type>

从其他博客系统 迁移内容.
Hexo 支持从 RSS/Jekyll/Octopress/WordPress/Joomla 等博客系统的内容迁移到 Hexo.

clean

1
hexo clean

清除缓存文件 (db.json) 和已生成的静态文件 (public).

在某些情况(尤其是更换主题后),如果发现您对站点的更改无论如何也不生效,您可能需要运行该命令.

list

1
hexo list <type>

列出网站资料(偏统计信息一些).

type Available types: page, post, route, tag, category

version

1
hexo version

命令选项

1
2
3
4
5
6
7
hexo --safe # 安全模式.安全模式下,不会载入插件和脚本.在安装新插件遭遇问题时,可以尝试以安全模式重新执行.
hexo --debug # 调试模式.在终端中显示调试信息并记录到 debug.log.
hexo --silent # 简洁模式.
hexo server --config # 自定义配置文件的路径
hexo generate --config # 自定义配置文件的路径
hexo --draft # 显示草稿
hexo --cwd /path/to/cwd # 自定义 CWD

Tag Plugins标签插件

tag plugins 从 Octopress 继承而来, 可以用来快速添加某些特定形式的内容. 并且不像 markdown 的某些语法会出现解析错误等情况, tag plugins 则能保证一定会实现语法规定的效果:

Although you can write your posts in any formats, but the tag plugins will always be available and syntax remains the same.

语法使用上的注意点: Tag plugins should not be wrapped inside Markdown syntax, e.g. []({% post_path lorem-ipsum %}) is not supported.

下面介绍可用的种类:

Block Quote

用途: 添加块状引用.

别名: quote

用法:

1
2
3
{% blockquote [author[, source]] [link] [source_link_title] %}
content
{% endblockquote %}

例子:

  1. 无格式引用:

    1
    2
    3
    {% blockquote %}
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque hendrerit lacus ut purus iaculis feugiat. Sed nec tempor elit, quis aliquam neque. Curabitur sed diam eget dolor fermentum semper at eu lorem.
    {% endblockquote %}

    效果:

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque hendrerit lacus ut purus iaculis feugiat. Sed nec tempor elit, quis aliquam neque. Curabitur sed diam eget dolor fermentum semper at eu lorem.

  2. 引用书籍

    1
    2
    3
    {% blockquote David Levithan, Wide Awake %}
    Do not just seek happiness for yourself. Seek happiness for all. Through kindness. Through mercy.
    {% endblockquote %}

    效果:

    Do not just seek happiness for yourself. Seek happiness for all. Through kindness. Through mercy.

    David LevithanWide Awake

  3. 引用 twitter

    1
    2
    3
    {% blockquote @DevDocs https://twitter.com/devdocs/status/356095192085962752 %}
    NEW: DevDocs now comes with syntax highlighting. http://devdocs.io
    {% endblockquote %}

    效果:

    NEW: DevDocs now comes with syntax highlighting. http://devdocs.io

    @DevDocstwitter.com/devdocs/status/356095192085962752

  4. 引用网页内容

    1
    2
    3
    {% blockquote Seth Godin http://sethgodin.typepad.com/seths_blog/2009/07/welcome-to-island-marketing.html Welcome to Island Marketing %}
    Every interaction is both precious and an opportunity to delight.
    {% endblockquote %}

    效果:

    Every interaction is both precious and an opportunity to delight.

    Seth GodinWelcome to Island Marketing

Code Block 代码块

别名: code

用法:

1
2
3
{% codeblock [title] [lang:language] [url] [link text] [additional options] %}
code snippet
{% endcodeblock %}

选项:

Extra Options Description Default
line_number Show line number true
line_threshold Only show line numbers as long as the numbers of lines of the code block exceed such threshold. 0
highlight Enable code highlighting true
first_line Specify the first line number 1
mark Line highlight specific line(s), each value separated by a comma. Specify number range using a dash
Example: mark:1,4-7,10 will mark line 1, 4 to 7 and 10.
wrap Wrap the code block in <table> true

本节内容在 Hight.js 部分介绍过.不再进行详细的例子解释.

Backtick Code Block 反引号代码块

1
``` [language] [title] [url] [link text] code snippet ```

Pull Quote 重要引文

1
2
3
{% pullquote [class] %}
content
{% endpullquote %}

Image 图片

用途: 插入指定大小的图片.

1
{% img [class names] /path/to/image [width] [height] '"title text" "alt text"' %}
1
{% link text url [external] [title] %}

Include Code 代码包含

用途: 插入来自 source/downloads/code 文件夹的代码块, 文件夹也可以通过参数指定.

1
{% include_code [title] [lang:language] [from:line] [to:line] path/to/file %}

例子:

1
{% include_code lang:javascript from:5 test.js %}

指定文件的第5行到最后一行.

视频

YouTube

1
{% youtube video_id [type] [cookie] %}

例子:

插入一个视频:

1
{% youtube lJIrF4YjHfQ %}

插入一个 playlist:

1
{% youtube PL9hW1uS6HUfscJ9DHkOSoOX45MjXduUxo 'playlist' %}

开启安全保护模式(YouTube’s cookie is not used in this mode.)

1
2
{% youtube lJIrF4YjHfQ false %}
{% youtube PL9hW1uS6HUfscJ9DHkOSoOX45MjXduUxo 'playlist' false %}

Vimeo

1
{% vimeo video_id [width] [height] %}

Include Posts

用途: 插入自己站点的其他 post.

1
2
{% post_path filename %}
{% post_link filename [title] [escape] %}

可以省略 permalink 以及 folder information, 直接使用 .md 文件的文件名即可.

例子:

1
{% post_link how-to-bake-a-cake %}

This will work as long as the filename of the post is how-to-bake-a-cake.md, even if the post is located at source/posts/2015-02-my-family-holiday and has permalink 2018/en/how-to-bake-a-cake.

可以自定义博文的标题甚至使用转义字符, 例如:

显示博文的标题.

1
{% post_link hexo-3-8-released %}

Hexo 3.8.0 Released

显示自定义文本.

1
{% post_link hexo-3-8-released 'Link to a post' %}

Link to a post

对标题进行转义.

1
{% post_link hexo-4-released 'How to use <b> tag in title' %}

How to use tag in title

不对标题进行转义.

1
{% post_link hexo-4-released '<b>bold</b> custom title' false %}

bold custom title

Include Assets

需要配置文件中的 post_asset_folder 参数为 true. 在资源文件夹内容的讲解部分提到.

1
2
3
{% asset_path filename %}
{% asset_img [class names] slug [width] [height] [title text [alt text]] %}
{% asset_link filename [title] [escape] %}

以插入图片为例,

如在资源文件夹部分提及的那样, hexo-renderer-marked 3.1.0+ 可以自动解析图片路径.

Default (no option)

1
2
{% asset_img foo.jpg %}
<img src="/2020/01/02/hello/foo.jpg">

Custom class

1
2
{% asset_img post-image foo.jpg %}
<img src="/2020/01/02/hello/foo.jpg" class="post-image">

Display size

1
2
{% asset_img foo.jpg 500 400 %}
<img src="/2020/01/02/hello/foo.jpg" width="500" height="400">

Title & Alt

1
2
{% asset_img foo.jpg "lorem ipsum'dolor'" %}
<img src="/2020/01/02/hello/foo.jpg" title="lorem ipsum" alt="dolor">

Raw

用途: 如果你发现你的内容在处理后并没有按照语法显示, 可以使用此语法, 强制显示, 避免渲染错误.

1
2
3
{% raw %}
content
{% endraw %}

例如, 我遇到的数学公式的问题, 有很大数学公式符合语法, 在主流 markdown 编辑器下工作正常, 但是就是渲染不出来(尤其在涉及 P^* 这种带星号的前后). 这时候在渲染失败的块的前后添加此语法即可正常渲染公式.

但是这么做也有副作用, 那就是像 **content** 或者 ### title 3 这种 markdown 的语法也会无法正常解析. 换句话说在 raw 语法的内部不要使用 markdown 的语法. 如果不得不使用有2种办法:

  1. 把 content 块再进一步化成更细的块, 在 markdown 语法的前后使用 raw.

    1
    2
    3
    4
    5
    {% raw %}
    content_1
    ### title 3
    content_2
    {% endraw %}

    变为:

    1
    2
    3
    4
    5
    6
    7
    {% raw %}
    content_1
    {% endraw %}
    ### title 3
    {% raw %}
    content_2
    {% endraw %}
  2. 把 markdown 的语法换为 html 标签语法.

Post Excerpt 博文摘要

在文章中使用 <!-- more -->,那么 <!-- more --> 之前的文字将会被视为摘要.首页中将只出现这部分文字,同时这部分文字也会出现在正文之中.

注意,摘要可能会被 Front Matter 中的 excerpt 覆盖.

其他

1
2
3
{% jsfiddle shorttag [tabs] [skin] [width] [height] %} # 在文章中嵌入 jsFiddle
{% gist gist_id [filename] %} # 在文章中嵌入 Gist
{% iframe url [width] [height] %} # 在文章中插入 iframe

数据文件

有时您可能需要在主题中使用某些资料,而这些资料并不在文章内,并且是需要重复使用的,那么您可以考虑使用 Hexo 3.0 新增的「数据文件」功能.此功能会载入 source/_data 内的 YAML 或 JSON 文件,如此一来您便能在网站中复用这些文件了.

举例来说,在 source/_data 文件夹中新建 menu.yml 文件:

1
2
3
Home: /
Gallery: /gallery/
Archives: /archives/

您就能在模板中使用这些资料:

1
2
3
<% for (var link in site.data.menu) { %>
<a href="<%= site.data.menu[link] %>"> <%= link %> </a>
<% } %>

渲染结果如下 :

1
2
3
<a href="/"> Home </a>
<a href="/gallery/"> Gallery </a>
<a href="/archives/"> Archives </a>

部署

Hexo 提供了快速方便的一键部署功能,让您只需一条命令就能将网站部署到服务器上.

1
hexo deploy

在开始之前,您必须先在 _config.yml 中修改参数,一个正确的部署配置中至少要有 type 参数,例如:

1
2
deploy:
type: git

您可同时使用多个 deployer,Hexo 会依照顺序执行每个 deployer.

1
2
3
4
5
deploy:
- type: git
repo:
- type: heroku
repo:

Hexo 支持很多种部署系统, 这里只介绍 Git.

Git

步骤如下:

  1. 安装 hexo-deployer-git.
1
npm install hexo-deployer-git --save
  1. 修改配置.
1
2
3
4
5
deploy:
type: git
repo: <repository url> #https://bitbucket.org/JohnSmith/johnsmith.bitbucket.io
branch: [branch]
message: [message]
参数 描述 默认
repo 库(Repository)地址
branch 分支名称 master
message 自定义提交信息 Site updated: {{ now('YYYY-MM-DD HH:mm:ss') }})
token Optional token value to authenticate with the repo.
Prefix with $ to read token from environment variable
  1. 生成站点文件并推送至远程库.执行 hexo clean && hexo deploy.如果不想每次重复输入用户名/密码, 可以考虑使用 git-credential-cache to store them temporarily.

运行机理

当执行 hexo deploy 时,Hexo 会将 public 目录中的文件和目录推送至 _config.yml 中指定的远端仓库和分支中,并且完全覆盖该分支下的已有内容.

如果同时使用 Git 管理写作空间(站点目录)的话, 需要注意一下:

  • 由于 Hexo 的部署默认使用分支 master,你应当注意你的部署分支应当不同于写作分支.
  • 一个好的实践是将站点目录和 Pages 分别存放在两个不同的 Git 仓库中,可以有效避免相互覆盖.
  • Hexo 在部署你的站点生成的文件时并不会更新你的站点目录.因此你应该手动提交并推送你的写作分支.

其他部署系统/协议

Heroku, Netlify, rsync, OpenShift,FTPSync,SFTP,Vercel,21云盒子,Bip,RSS3.

详细参考官网教程.

或者手动把public 文件夹拷贝过去.

将 Hexo 部署到 GitHub Pages

使用 Travis CI 将 Hexo 博客部署到 GitHub Pages 上.Travis CI 对于开源 repository 是免费的,但是这意味着你的站点文件将会是公开的.具体做法参考官网教程.

将 Hexo 部署到 GitLab Pages

使用 GitLab CI 将 Hexo 博客部署到 GitLab Pages 上.官网教程.

主题

只要在 themes 文件夹内,新增一个任意名称的文件夹,并修改 _config.yml 内的 theme 设定,即可切换主题.一个主题可能会有以下的结构:

1
2
3
4
5
6
.
├── _config.yml # 主题的配置文件.和 Hexo 配置文件不同,主题配置文件修改时会自动更新,无需重启 Hexo Server.
├── languages # 语言文件夹.请参见 国际化 (i18n).
├── layout # 用于存放主题的模板文件,决定了网站内容的呈现方式,Hexo 内建 Nunjucks 模板引擎,或用其他引擎的插件
├── scripts # 在启动时,Hexo 会载入此文件夹内的 JavaScript 文件.
└── source # 除了模板以外的 Asset,例如 CSS,JavaScript 文件等.

发布

当您完成主题后,可以考虑将它发布到 主题列表,让更多人能够使用您的主题.在发布前建议先进行 主题单元测试,确保每一项功能都能正常使用.发布主题的步骤和 更新文档 非常类似.

页面模版

模板决定了网站内容的呈现方式,每个主题至少都应包含一个 index 模板,以下是各页面相对应的模板名称:

模板 用途 回退
index 首页 Home
post 文章 index
page 分页 index
archive 归档 index
category 分类归档 archive
tag 标签归档 archive

变量

全局变量

变量 描述 类型
site 网站变量 object; 见 网站变量
page 针对该页面的内容以及 front-matter 中自定义的变量. object; 见 页面变量
config 网站配置 object (站点的配置文件)
theme 主题配置.继承自网站配置. object (主题配置文件)
path 当前页面的路径(不含根路径) string
url 当前页面的完整网址 string
env 环境变量 ???

网站变量

变量 描述 类型
site.posts 所有文章 array of post objects
site.pages 所有分页 array of page objects
site.categories 所有分类 object,包含了站点全部的分类
site.tags 所有标签 array,包含了站点全部的标签

页面变量

页面(page)

变量 描述 类型
page.title 页面标题 string
page.date 页面建立日期 [Moment.js] 对象
page.updated 页面更新日期 [Moment.js] 对象
page.comments 留言是否开启 boolean
page.layout 布局名称 string
page.content 页面的完整内容 string
page.excerpt 页面摘要 string
page.more 除了页面摘要的其余内容 string
page.source 页面原始路径 string
page.full_source 页面的完整原始路径 string
page.path 页面网址(不含根路径).我们通常在主题中使用 url_for(page.path). string
page.permalink 页面的完整网址 string
page.prev 上一个页面.如果此为第一个页面则为 null. string or null
page.next 下一个页面.如果此为最后一个页面则为 null. string or null
page.raw 文章的原始内容 ???
page.photos 文章的照片(用于相簿) array
page.link 文章的外部链接(用于链接文章) string

文章 (post):

page 布局相同,但新增以下变量

变量 描述 类型
page.published 如果该文章已发布则为 true boolean
page.categories 该文章的所有分类 array of ???
page.tags 该文章的所有标签 array of ???

首页(index)

变量 描述 类型
page.per_page 每页显示的文章数量 number
page.total 总页数 number
page.current 目前页数 number
page.current_url 目前分页的网址 string
page.posts 本页文章 (Data Model) object
page.prev 上一页的页数.如果此页是第一页的话则为 0. number
page.prev_link 上一页的网址.如果此页是第一页的话则为 ''. string
page.next 下一页的页数.如果此页是最后一页的话则为 0. number
page.next_link 下一页的网址.如果此页是最后一页的话则为 ''. string
page.path 当前页面的路径(不含根目录).我们通常在主题中使用 url_for(page.path). string

归档 (archive)

index 布局相同,但新增以下变量.

变量 描述 类型
page.archive 等于 true boolean
page.year 年份归档 (4位) number
page.month 月份归档 (没有前导零的2位数) number

分类 (category)

index 布局相同,但新增以下变量.

变量 描述 类型
page.category 分类名称 string

标签 (tag)

index 布局相同,但新增以下变量.

变量 描述 类型
page.tag 标签名称 string

辅助函数(Helpers)

有点涉及到前端的编程技术了, 不深究, 网址.

国际化(i18n)

需要时再看吧, 网址.

插件

在 Hexo 中有两种形式的插件:

脚本(Scripts)

如果您的代码很简单,建议您编写脚本,您只需要把 JavaScript 文件放到 scripts 文件夹,在启动时就会自动载入.

插件(Packages)

如果您的代码较复杂,或是您想要发布到 NPM 上,建议您编写插件.首先,在 node_modules 文件夹中建立文件夹,文件夹名称开头必须为 hexo-,如此一来 Hexo 才会在启动时载入;否则 Hexo 将会忽略它.

文件夹内至少要包含 2 个文件:一个是主程序,另一个是 package.json,描述插件的用途和所依赖的插件.

1
2
3
.
├── index.js
└── package.json

package.json 中至少要包含 name, version, main 属性,例如:

1
2
3
4
5
package.json{
"name": "hexo-my-plugin",
"version": "0.0.1",
"main": "index"
}

工具

您可以使用 Hexo 提供的官方工具插件来加速开发:

发布

当您完成插件后,可以考虑将它发布到 插件列表,让更多人能够使用您的插件.发布插件的步骤和 更新文件 非常类似.

常见问题解答

网址.

作者

cx

发布于

2022-03-20

更新于

2022-07-16

许可协议