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:
npx hexo <command>
- 将 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 | hexo init <folder> |
新建完成后,指定文件夹的目录如下:
1 | . |
配置
_config.yml
中, 汇总简介如下, 很多一看之下可能无法理解, 后面会逐个解释.
1 | # # |
网站存放在子目录
如果您的网站存放在子目录中,例如 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
来预览草稿.
扩展
include
和 exclude
选项
在 Hexo 配置文件中,通过设置 include/exclude 可以让 Hexo 进行处理或忽略某些目录和文件夹.你可以使用 glob 表达式 对目录和文件进行匹配.
include
和 exclude
选项只会应用到 source/
,而 ignore
选项会应用到所有文件夹.
参数 | 描述 |
---|---|
include | Hexo 默认会不包括 source/ 下的隐藏类文件和文件夹(包括名称以下划线和 . 开头的文件和文件夹,Hexo 的 _posts 和 _data 等目录除外).通过设置此字段将使 Hexo 处理他们并将它们复制到 source 目录下. |
exclude | Hexo 不包括 source/ 下的这些文件和目录 |
ignore | Hexo 会忽略整个 Hexo 项目下的这些文件夹或文件 |
举例:
1 | # 处理或不处理目录或文件 |
列表中的每一项都必须用单引号或双引号包裹起来.
include
和 exclude
并不适用于 themes/
目录下的文件.如果需要忽略 themes/
目录下的部分文件或文件夹,可以使用 ignore
或在文件名之前添加下划线 _
.
使用代替配置文件
hexo-cli
中使用 --config
参数来指定自定义配置文件的路径,支持 YAML 或 JSON 文件格式. 可以使用一个配置文件的路径,也可以使用逗号分隔(无空格)的多个配置文件的路径.例如:
1 | # 用 'custom.yml' 代替 '_config.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 | # _config.yml |
最终主题配置的输出是:
1 | { |
独立的 _config.[theme].yml
文件
该特性自 Hexo 5.0.0 起提供.
独立的主题配置文件应放置于站点根目录下,支持 yml
或 json
格式.需要配置站点 _config.yml
文件中的 theme
以供 Hexo 寻找 _config.[theme].yml
文件.
1 | # _config.yml |
最终主题配置的输出是:
1 | { |
强烈建议你将所有的主题配置集中在一处.
文章模版(Scaffold)
1 | hexo new photo "My Gallery" |
在执行这行指令时,Hexo 会尝试在 scaffolds
文件夹中寻找 photo.md
,并根据其内容建立文章,以下是您可以在模版中使用的变量:
变量 | 描述 |
---|---|
layout | 布局 |
title | 标题 |
date | 文件建立日期 |
支持的格式
Hexo 支持以任何格式书写文章,只要安装了相应的渲染插件.
例如,Hexo 默认安装了 hexo-renderer-marked
和 hexo-renderer-ejs
,因此你不仅可以用 Markdown 写作,你还可以用 EJS 写作.如果你安装了 hexo-renderer-pug
,你甚至可以用 Pug 模板语言书写文章.
只需要将文章的扩展名从 md
改成 ejs
,Hexo 就会使用 hexo-renderer-ejs
渲染这个文件,其他格式同理.
Front-matter
文件最上方以 ---
分隔的区域,用于指定个别文件的变量.
例如:
1 | --- |
一些预先定义的参数,可在模板中使用这些参数值.
参数 | 描述 | 默认值/用法 |
---|---|---|
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 | categories: |
该文章属于 Blog 大类, Diary 小类, 标签为 PS3 以及 Games.
Hexo 不支持指定多个同级分类( WordPress 支持).
如果你需要为文章添加多个分类,可以尝试以下 list 中的方法.
1 | categories: |
此时这篇文章同时包括三个分类: PlayStation
和 Games
分别都是父分类 Diary
的子分类,同时 Life
是一个没有子分类的分类.
JSON Front-matter
除了 YAML 外,你也可以使用 JSON 来编写 Front-matter,只要将 ---
代换成 ;;;
即可.
1 | "title": "Hello World", |
Hexo 生成的超链接
默认情况下,Hexo 生成的超链接都是绝对地址.例如,如果您的网站域名为 example.com
,您有一篇文章名为 hello
,那么绝对链接可能像这样:http://example.com/hello.html
,它是绝对于域名的.相对链接像这样:/hello.html
,也就是说,无论用什么域名访问该站点,都没有关系,这在进行反向代理时可能用到.通常情况下,建议使用绝对地址.
资源文件夹
资源(Asset)代表 source
文件夹中除了文章以外的所有文件,例如图片,CSS,JS 文件等.
有 3 种方式可以用来管理资源:
放到
source
文件夹下进行管理, 并通过 markdonw 的![]()
语法进行引用. 例如: 图片放入source/images
中, 文章使用![](/images/image.jpg)
的形式进行引用.通过文章分门别类管理资源: 首先
config.yml
文件中的post_asset_folder
选项设为true
来打开此功能. 然后 Hexo 将会在你每一次通过hexo new [layout] <title>
命令创建新文章时自动创建一个文件夹.这个资源文件夹将会有与这个文章文件一样的名字.将所有与你的文章有关的资源放在这个关联文件夹中之后,你可以通过相对路径来引用它们.通过常规的 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
永久链接(Permalinks)
可以在 _config.yml
配置中调整网站的永久链接或者在每篇文章的 Front-matter 中指定.注意永久链接的变动可能会影响 SEO.
例如: _config.yml
中 permalink_defaults
参数下调整永久链接中各变量的默认值:
1 | permalink_defaults: |
变量
除了下列变量外,您还可使用 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 | title: Hello Worl |
参数 | 结果 |
---|---|
: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 | title: Hello World2 |
参数 | 结果 |
---|---|
: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_name
和 permalink
参数,如下:
1 | new_post_name: :lang/:title.md |
当您建立新文章时,文章会被储存到:
1 | hexo new "Hello World" --lang tw |
而网址会是:
1 | http://localhost:4000/tw/hello-world/ |
Syntax Highlighting
Hexo 有2个内置的 syntax highlight 库, highlight.js and prismjs.
代码段的三种格式
1 | {% codeblock [title] [lang:language] [url] [link text] [additional options] %} |
Tag Plugin - Backtick Code Block:
1 | {% code [title] [lang:language] [url] [link text] [additional options] %} |
Markdown:
1 | ``` [language] [title] [url] [link text] [additional options] |
Hexo 支持 ejs, swig, nunjucks, pug, asciidoc, etc 格式, 只要安装了相应的 renderer plugin.
配置
1 | # _config.yml |
如果两个渲染插件都被 disable, 那么会使用默认的渲染器, 例如 hexo-renderer-marked , 然后转换为 html 的 <code>
标签.
1 | ```yaml |
1 | <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 tofalse
,wrap
is set to false andhljs
is set totrue
, you can then usehighlight.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 默认在目前的文件夹建立网站.
本命令相当于执行了以下几步:
- Git clone hexo-starter 和 hexo-theme-landscape 主题到当前目录或指定目录.
- 使用 Yarn 1,pnpm 或 npm 包管理器下载依赖(如有已安装多个,则列在前面的优先).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 | hexo 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 | hexo deploy |
部署网站.-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 | hexo --safe # 安全模式.安全模式下,不会载入插件和脚本.在安装新插件遭遇问题时,可以尝试以安全模式重新执行. |
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 | {% blockquote [author[, source]] [link] [source_link_title] %} |
例子:
无格式引用:
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.
引用书籍
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
引用 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
引用网页内容
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 | {% codeblock [title] [lang:language] [url] [link text] [additional options] %} |
选项:
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 | {% pullquote [class] %} |
Image 图片
用途: 插入指定大小的图片.
1 | {% img [class names] /path/to/image [width] [height] '"title text" "alt text"' %} |
Link 链接
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 | {% youtube lJIrF4YjHfQ false %} |
Vimeo
1 | {% vimeo video_id [width] [height] %} |
Include Posts
用途: 插入自己站点的其他 post.
1 | {% post_path filename %} |
可以省略 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 %} |
显示自定义文本.
1 | {% post_link hexo-3-8-released 'Link to a post' %} |
对标题进行转义.
1 | {% post_link hexo-4-released 'How to use <b> tag in title' %} |
不对标题进行转义.
1 | {% post_link hexo-4-released '<b>bold</b> custom title' false %} |
Include Assets
需要配置文件中的 post_asset_folder
参数为 true. 在资源文件夹内容的讲解部分提到.
1 | {% asset_path filename %} |
以插入图片为例,
如在资源文件夹部分提及的那样, hexo-renderer-marked 3.1.0+ 可以自动解析图片路径.
Default (no option)
1 | {% asset_img foo.jpg %} |
Custom class
1 | {% asset_img post-image foo.jpg %} |
Display size
1 | {% asset_img foo.jpg 500 400 %} |
Title & Alt
1 | {% asset_img foo.jpg "lorem ipsum'dolor'" %} |
Raw
用途: 如果你发现你的内容在处理后并没有按照语法显示, 可以使用此语法, 强制显示, 避免渲染错误.
1 | {% raw %} |
例如, 我遇到的数学公式的问题, 有很大数学公式符合语法, 在主流 markdown 编辑器下工作正常, 但是就是渲染不出来(尤其在涉及 P^*
这种带星号的前后). 这时候在渲染失败的块的前后添加此语法即可正常渲染公式.
但是这么做也有副作用, 那就是像 **content**
或者 ### title 3
这种 markdown 的语法也会无法正常解析. 换句话说在 raw 语法的内部不要使用 markdown 的语法. 如果不得不使用有2种办法:
把 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 %}把 markdown 的语法换为 html 标签语法.
Post Excerpt 博文摘要
在文章中使用 <!-- more -->
,那么 <!-- more -->
之前的文字将会被视为摘要.首页中将只出现这部分文字,同时这部分文字也会出现在正文之中.
注意,摘要可能会被 Front Matter 中的 excerpt
覆盖.
其他
1 | {% jsfiddle shorttag [tabs] [skin] [width] [height] %} # 在文章中嵌入 jsFiddle |
数据文件
有时您可能需要在主题中使用某些资料,而这些资料并不在文章内,并且是需要重复使用的,那么您可以考虑使用 Hexo 3.0 新增的「数据文件」功能.此功能会载入 source/_data
内的 YAML 或 JSON 文件,如此一来您便能在网站中复用这些文件了.
举例来说,在 source/_data
文件夹中新建 menu.yml
文件:
1 | Home: / |
您就能在模板中使用这些资料:
1 | <% for (var link in site.data.menu) { %> |
渲染结果如下 :
1 | <a href="/"> Home </a> |
部署
Hexo 提供了快速方便的一键部署功能,让您只需一条命令就能将网站部署到服务器上.
1 | hexo deploy |
在开始之前,您必须先在 _config.yml
中修改参数,一个正确的部署配置中至少要有 type
参数,例如:
1 | deploy: |
您可同时使用多个 deployer,Hexo 会依照顺序执行每个 deployer.
1 | deploy: |
Hexo 支持很多种部署系统, 这里只介绍 Git.
Git
步骤如下:
1 | npm install hexo-deployer-git --save |
- 修改配置.
1 | deploy: |
参数 | 描述 | 默认 |
---|---|---|
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 |
- 生成站点文件并推送至远程库.执行
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 | . |
发布
当您完成主题后,可以考虑将它发布到 主题列表,让更多人能够使用您的主题.在发布前建议先进行 主题单元测试,确保每一项功能都能正常使用.发布主题的步骤和 更新文档 非常类似.
页面模版
模板决定了网站内容的呈现方式,每个主题至少都应包含一个 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 | . |
package.json
中至少要包含 name
, version
, main
属性,例如:
1 | package.json{ |
工具
您可以使用 Hexo 提供的官方工具插件来加速开发:
- hexo-fs:文件 IO
- hexo-util:工具程式
- hexo-i18n:本地化(i18n)
- hexo-pagination:生成分页资料
发布
当您完成插件后,可以考虑将它发布到 插件列表,让更多人能够使用您的插件.发布插件的步骤和 更新文件 非常类似.
常见问题解答
网址.