Hexo站点配置

本文将详细介绍 Hexo 站点配置文件中的各个配置项的含义与作用。

参考官方文档 Hexo

本文基于 hexo: 3.8.0

站点配置文件

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
# Hexo Configuration
## Docs: https://hexo.io/docs/configuration.html
## Source: https://github.com/hexojs/hexo/

# Site
title: Hexo
subtitle:
description:
keywords:
author: John Doe
language:
timezone:

# URL
## If your site is put in a subdirectory, set url as 'http://yoursite.com/child' and root as '/child/'
url: http://yoursite.com
root: /
permalink: :year/:month/:day/:title/
permalink_defaults:

# Directory
source_dir: source
public_dir: public
tag_dir: tags
archive_dir: archives
category_dir: categories
code_dir: downloads/code
i18n_dir: :lang
skip_render:

# Writing
new_post_name: :title.md # File name of new posts
default_layout: post
titlecase: false # Transform title into titlecase
external_link: true # Open external links in new tab
filename_case: 0
render_drafts: false
post_asset_folder: false
relative_link: false
future: true
highlight:
enable: true
line_number: true
auto_detect: false
tab_replace:

# Home page setting
# path: Root path for your blogs index page. (default = '')
# per_page: Posts displayed per page. (0 = disable pagination)
# order_by: Posts order. (Order by date descending by default)
index_generator:
path: ''
per_page: 10
order_by: -date

# Category & Tag
default_category: uncategorized
category_map:
tag_map:

# Date / Time format
## Hexo uses Moment.js to parse and display date
## You can customize the date format as defined in
## http://momentjs.com/docs/#/displaying/format/
date_format: YYYY-MM-DD
time_format: HH:mm:ss

# Pagination
## Set per_page to 0 to disable pagination
per_page: 10
pagination_dir: page

# Extensions
## Plugins: https://hexo.io/plugins/
## Themes: https://hexo.io/themes/
theme: landscape

# Deployment
## Docs: https://hexo.io/docs/deployment.html
deploy:
type:

Site

Setting Description
title 站点名称
subtitle 站点副标题
description 站点描述
author 作者名称
language 网站使用的语言
timezone 网站时区。Hexo 默认使用本机的时区,可用时区列表,例如:America/New_York, Japan, 和 UTC

其中,description 主要用于 SEO,告诉搜索引擎一个关于站点的简单描述,通常建议在其中包含网站的关键词,也可以是你喜欢的一句签名。author 参数用于主题显示文章的作者。

对应于 NexT 主题 Gemini scheme 的显示效果下,不同主题显示效果不同,但原理类似。

Site-title

Site-subtitle

Site-author-description

URL

Setting Description Default
url 网站的URL
root 网站根目录
permalink 文章的永久链接格式 :year/:month/:day/:title/
permalink_defaults 永久链接中各部分的默认值

如果网站存放在子目录中,例如 http://yoursite.com/blog,则需要将 url 设为 http://yoursite.com/blog 并把 root 设为 /blog/

Directory

Setting Description Default
source_dir 资源文件夹,用来存放源文件,如文章的markdown文件 source
public_dir 公共文件夹,用来存放生成的站点文件 public
tag_dir 标签文件夹 tags
archive_dir 归档文件夹 archives
category_dir 分类文件夹 categories
code_dir Include code 文件夹 downloads/code
i18n_dir 国际化(i18n)文件夹 :lang
skip_render 跳过指定文件的渲染,可以使用glob表达式来匹配路径, 如跳过README.md的渲染

Writing

Setting Description Description
new_post_name 新文章的文件名称 :title.md
default_layout 默认布局 post
titlecase 把标题转换为 title case false
external_link 在新标签中打开链接 true
filename_case 把文件名称转换为"1"小写或"2"大写 0
render_drafts 显示草稿 false
post_asset_folder 同步创建资源文件夹 false
relative_link 把链接改为与根目录的相对地址 false
future 显示未来的文章 true
highlight 代码块的设置

filename_case

filename_case 默认值为 0,表示不做任何处理,为 1 则转为小写,为 2 则转为大写。

post_asset_folder

设置 post_asset_folder 为 true 后,每次新建文章都会自动创建一个同名的文件夹,用于存放一些图片文件,方便管理文章的图片资源,创建的文件夹与新建文章在目录结构上是同级关系。

相对地址

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

highlight

Setting Description Default
enable 启用代码高亮 true
line_number 显示行号 true
auto_detect 自动检测语言 false
tab_replace 使用指定字符串替换tab键

tab_replace 会将代码块中所有的tab键都换成指定的字符串,例如:

1
2
3
4
5
highlight:
enable: true
line_number: true
auto_detect: false
tab_replace: true

那么所有的tab键都会被替换成字符串"true", 假设原代码为:

1
2
3
4
5
class Main {
public static void main(String[] args) {
System.out.println("Hello World!");
}
}

替换后为:

1
2
3
4
5
class Main {
truepublic static void main(String[] args) {
truetrueSystem.out.println("Hello World!");
true}
}

Home page setting

主页显示配置

Setting Description Default
path 博客主页根路径 ''
per_page 每页展示文章数量 (0 = 关闭分页功能) 10
order_by 排序,默认按时间降序排列 -date

Category & Tag

Setting Description Default
default_category 默认分类 uncategorized
category_map 分类别名
tag_map 标签别名

Date / Time format

Hexo 使用 Moment.js 来解析和显示时间。

Setting Description Default
date_format 日期格式 YYYY-MM-DD
time_format 时间格式 H:mm:ss

Pagination

Setting Description Default
per_page 每页显示的文章数量 (0 = 关闭分页功能) 10
pagination_dir 分页目录 page

Extensions

Setting Description Default
theme 当前主题名称,值为false时禁用主题 landscape

Deployment

Setting Description
deploy 部署部分的设置

例如:

1
2
3
4
5
deploy:
type: git
repo: <repository url> # https://bitbucket.org/JohnSmith/johnsmith.bitbucket.io
branch: [branch name] # published
message: [commit message]
Setting Description
type deployer
repo 仓库库(Repository)地址
branch 分支名称,如果使用的是 GitHub 或 GitCafe 的话,程序会尝试自动检测
message 自定义提交信息 (默认为 Site updated: {{ now('YYYY-MM-DD HH:mm:ss') }})

一个正确的部署配置中至少要有 type 参数,例如:

1
2
deploy:
type: git

可以同时使用多个 deployer,Hexo 会依照顺序执行每个 deployer,例如:

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

添加 README.md 文件

Hexo 默认会将 source 文件夹下的 md 文件渲染成 html 文件,所以使用 hexo 部署到仓库后,项目下是没有 README.md 文件的。在 Hexo 目录下的 source 根目录下添加一个 README.md 文件,修改 站点配置文件,skip_render 参数的值设置如下:

1
skip_render: README.md

表示在执行 hexo g 时跳过渲染 README.md 这个文件。