Hexo 框架使用手册
开始使用
欢迎使用 Hexo,本文档将帮助您快速上手。如果您在使用过程中遇到问题,请查看 问题解答 中的解答,或者在 GitHub、Google Group 上提问。
概述
什么是 Hexo?
Hexo 是一个快速、简洁且高效的博客框架。Hexo 使用 Markdown(或其他渲染引擎)解析文章,在几秒内,即可利用靓丽的主题生成静态网页。
安装
安装 Hexo 只需几分钟时间,若您在安装过程中遇到问题或无法找到解决方式,请 提交问题,我们会尽力解决您的问题。
安装前提
安装 Hexo 相当简单,只需要先安装下列应用程序即可:
如果您的电脑中已经安装上述必备程序,那么恭喜您!你可以直接前往 安装 Hexo 步骤。
如果您的电脑中尚未安装所需要的程序,请根据以下安装指示完成安装。
安装 Git
- Windows:下载并安装 git.
- Mac:使用 Homebrew, MacPorts 或者下载 安装程序。
- Linux (Ubuntu, Debian):
sudo apt-get install git-core
- Linux (Fedora, Red Hat, CentOS):
sudo yum install git-core
Mac 用户
如果在编译时可能会遇到问题,请先到 App Store 安装 Xcode,Xcode 完成后,启动并进入 Preferences -> Download -> Command Line Tools -> Install 安装命令行工具。
Windows 用户
对于中国大陆地区用户,可以前往 淘宝 Git for Windows 镜像 下载 git 安装包。
安装 Node.js
Node.js 为大多数平台提供了官方的 安装程序。对于中国大陆地区用户,可以前往 淘宝 Node.js 镜像 下载。
其它的安装方法:
- Windows:通过 nvs(推荐)或者 nvm 安装。
- Mac:使用 Homebrew 或 MacPorts 安装。
- Linux(DEB/RPM-based):从 NodeSource 安装。
- 其它:使用相应的软件包管理器进行安装,可以参考由 Node.js 提供的 指导。
对于 Mac 和 Linux 同样建议使用 nvs 或者 nvm,以避免可能会出现的权限问题。
Windows 用户
使用 Node.js 官方安装程序时,请确保勾选 Add to PATH 选项(默认已勾选)
For Mac / Linux 用户
如果在尝试安装 Hexo 的过程中出现 EACCES
权限错误,请遵循 由 npmjs 发布的指导 修复该问题。
强烈建议 不要 使用 root、sudo 等方法覆盖权限
Linux
如果您使用 Snap 来安装 Node.js,在 初始化 博客时您可能需要手动在目标文件夹中执行 npm install
。
安装 Hexo
所有必备的应用程序安装完成后,即可使用 npm 安装 Hexo。
1 | $ npm install -g hexo-cli |
进阶安装和使用
对于熟悉 npm 的进阶用户,可以仅局部安装 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
网站的 配置 信息,您可以在此配置大部分的参数。
package.json
应用程序的信息。EJS, Stylus 和 Markdown renderer 已默认安装,您可以自由移除。
1 | package.json |
scaffolds
模版 文件夹。当您新建文章时,Hexo 会根据 scaffold 来建立文件。
Hexo的模板是指在新建的文章文件中默认填充的内容。例如,如果您修改scaffold/post.md中的Front-matter内容,那么每次新建一篇文章时都会包含这个修改。
source
资源文件夹是存放用户资源的地方。除 _posts
文件夹之外,开头命名为 _
(下划线)的文件 / 文件夹和隐藏的文件将会被忽略。Markdown 和 HTML 文件会被解析并放到 public
文件夹,而其他文件会被拷贝过去。
themes
主题 文件夹。Hexo 会根据主题来生成静态页面。
配置
您可以在 _config.yml
中修改大部分的配置。
网站
参数 | 描述 |
---|---|
title |
网站标题 |
subtitle |
网站副标题 |
description |
网站描述 |
keywords |
网站的关键词。支持多个关键词。 |
author |
您的名字 |
language |
网站使用的语言。对于简体中文用户来说,使用不同的主题可能需要设置成不同的值,请参考你的主题的文档自行设置,常见的有 zh-Hans 和 zh-CN 。 |
timezone |
网站时区。Hexo 默认使用您电脑的时区。请参考 时区列表 进行设置,如 America/New_York , Japan , 和 UTC 。一般的,对于中国大陆地区可以使用 Asia/Shanghai 。 |
其中,description
主要用于SEO,告诉搜索引擎一个关于您站点的简单描述,通常建议在其中包含您网站的关键词。author
参数用于主题显示文章的作者。
网址
参数 | 描述 | 默认值 |
---|---|---|
url |
网址, 必须以 http:// 或 https:// 开头 |
|
root |
网站根目录 | url's pathname |
permalink |
文章的 永久链接 格式 | :year/:month/:day/:title/ |
permalink_defaults |
永久链接中各部分的默认值 | |
pretty_urls |
改写 permalink 的值来美化 URL | |
pretty_urls.trailing_index |
是否在永久链接中保留尾部的 index.html,设置为 false 时去除 | true |
pretty_urls.trailing_html |
是否在永久链接中保留尾部的 .html , 设置为 false 时去除 (对尾部的 index.html 无效) |
true |
网站存放在子目录
如果您的网站存放在子目录中,例如 http://example.com/blog
,则请将您的 url
设为 http://example.com/blog
并把 root
设为 /blog/
。
例如:
1 | # 比如,一个页面的永久链接是 http://example.com/foo/bar/index.html |
目录
参数 | 描述 | 默认值 |
---|---|---|
source_dir |
资源文件夹,这个文件夹用来存放内容。 | source |
public_dir |
公共文件夹,这个文件夹用于存放生成的站点文件。 | public |
tag_dir |
标签文件夹 | tags |
archive_dir |
归档文件夹 | archives |
category_dir |
分类文件夹 | categories |
code_dir |
Include code 文件夹,source_dir 下的子目录 |
downloads/code |
i18n_dir |
国际化(i18n)文件夹 | :lang |
skip_render |
跳过指定文件的渲染。匹配到的文件将会被不做改动地复制到 public 目录中。您可使用 glob 表达式来匹配路径。 |
例如:
1 | skip_render: "mypage/**/*" |
提示
如果您刚刚开始接触 Hexo,通常没有必要修改这一部分的值。
文章
参数 | 描述 | 默认值 |
---|---|---|
new_post_name |
新文章的文件名称 | :title.md |
default_layout |
预设布局 | post |
auto_spacing |
在中文和英文之间加入空格 | false |
titlecase |
把标题转换为 title case | false |
external_link |
在新标签中打开链接 | true |
external_link.enable |
在新标签中打开链接 | true |
external_link.field |
对整个网站(site )生效或仅对文章(post )生效 |
site |
external_link.exclude |
需要排除的域名。主域名和子域名如 www 需分别配置 |
[] |
filename_case |
把文件名称转换为 (1) 小写或 (2) 大写 | 0 |
render_drafts |
显示草稿 | false |
post_asset_folder |
启动 Asset 文件夹 | false |
relative_link |
把链接改为与根目录的相对位址 | false |
future |
显示未来的文章 | true |
highlight |
代码块的设置, 请参考 Highlight.js 进行设置 | |
prismjs |
代码块的设置, 请参考 PrismJS 进行设置 |
相对地址
默认情况下,Hexo 生成的超链接都是绝对地址。例如,如果您的网站域名为 example.com
,您有一篇文章名为 hello
,那么绝对链接可能像这样:http://example.com/hello.html
,它是绝对于域名的。相对链接像这样:/hello.html
,也就是说,无论用什么域名访问该站点,都没有关系,这在进行反向代理时可能用到。通常情况下,建议使用绝对地址。
分类 & 标签
参数 | 描述 | 默认值 |
---|---|---|
default_category |
默认分类 | uncategorized |
category_map |
分类别名 | |
tag_map |
标签别名 |
日期 / 时间格式
Hexo 使用 Moment.js 来解析和显示时间。
参数 | 描述 | 默认值 |
---|---|---|
date_format |
日期格式 | YYYY-MM-DD |
time_format |
时间格式 | HH:mm:ss |
updated_option |
当 Front Matter 中没有指定 updated 时 updated 的取值 |
mtime |
updated_optionupdated_option
控制了当 Front Matter 中没有指定 updated
时,updated
如何取值:
mtime
: 使用文件的最后修改时间。这是从 Hexo 3.0.0 开始的默认行为。date
: 使用date
作为updated
的值。可被用于 Git 工作流之中,因为使用 Git 管理站点时,文件的最后修改日期常常会发生改变empty
: 直接删除updated
。使用这一选项可能会导致大部分主题和插件无法正常工作。
use_date_for_updated
选项已经被废弃,将会在下个重大版本发布时去除。请改为使用 updated_option: 'date'
。
use_date_for_updated
| 启用以后,如果 Front Matter 中没有指定 updated
, post.updated 将会使用 date
的值而不是文件的创建时间。在 Git 工作流中这个选项会很有用 | true
分页
参数 | 描述 | 默认值 |
---|---|---|
per_page |
每页显示的文章量 (0 = 关闭分页功能) | 10 |
pagination_dir |
分页目录 | page |
扩展
参数 | 描述 |
---|---|
theme |
当前主题名称。值为 false 时禁用主题 |
theme_config |
主题的配置文件。在这里放置的配置会覆盖主题目录下的 _config.yml 中的配置 |
deploy |
部署部分的设置 |
meta_generator |
Meta generator 标签。 值为 false 时 Hexo 不会在头部插入该标签 |
包括或不包括目录和文件
在 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 文件的路径,也可以使用逗号分隔(无空格)的多个 YAML 或 JSON 文件的路径。例如:
1 | # 用 'custom.yml' 代替 '_config.yml' |
当你指定了多个配置文件以后,Hexo 会按顺序将这部分配置文件合并成一个 _multiconfig.yml
。如果遇到重复的配置,排在后面的文件的配置会覆盖排在前面的文件的配置。这个原则适用于任意数量、任意深度的 YAML 和 JSON 文件。
例如,使用 --options
指定了两个自定义配置文件:
1 | $ hexo generate --config custom.yml,custom2.json |
如果 custom.yml
中指定了 foo: bar
,在 custom2.json 中指定了 "foo": "dinosaur"
,那么在 _multiconfig.yml
中你会得到 foo: dinosaur
。
使用代替主题配置文件
通常情况下,Hexo 主题是一个独立的项目,并拥有一个独立的 _config.yml
配置文件。
除了自行维护独立的主题配置文件,你也可以在其它地方对主题进行配置。
配置文件中的 theme_config
该特性自 Hexo 2.8.2 起提供
1 | # _config.yml |
1 | # themes/my-theme/_config.yml |
最终主题配置的输出是:
1 | { |
独立的 _config.[theme].yml
文件
该特性自 Hexo 5.0.0 起提供
独立的主题配置文件应放置于站点根目录下,支持 yml
或 json
格式。需要配置站点 _config.yml
文件中的 theme
以供 Hexo 寻找 _config.[theme].yml
文件。
1 | # _config.yml |
1 | # _config.my-theme.yml |
1 | # themes/my-theme/_config.yml |
最终主题配置的输出是:
1 | { |
我们强烈建议你将所有的主题配置集中在一处。如果你不得不在多处配置你的主题,那么这些信息对你将会非常有用:Hexo 在合并主题配置时,Hexo 配置文件中的 theme_config
的优先级最高,其次是 _config.[theme].yml
文件,最后是位于主题目录下的 _config.yml
文件。