基于Hexo和Butterfly创建个人技术博客，(6) 定制个人网站的Layout模板-帮助函数

Hexo官司网查看 这里

在前面章节提到过layou模板和布局的知识，严格来说之前讲的只是模板文件，真正布局的核心应该是网页的UI样式模板。庆幸的是这个UI样式也是可以自定义的但相对复杂一些，需要专业的编程知识。本节只是先列出一些字典函数供使用时查询，详细使用方法在后续的自定义个人主题时再讲解，此处大家可以浏览一下看看哪些网页内容是可以定制化的。

此文中函数的使用场景及要求：

1. 当开源的theme不能满足需求时，可修改theme的源码实现个性化定制；
2. 需要专业的前端编码能力，对于普通用户可跳过此单内容；
3. 此文中所有的函数只能在定制模板时使用，不能用于普通文章的编写；

本章目标：
针对有编程能力的同学，需要掌握常用的hepler函数的用法

一、Hexo变量

全局变量

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

网站变量

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

二、普通页面变量

页面变量(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。	object 或 null
page.next	下一个页面。如果此为最后一个页面则为 null。	object 或 null
page.raw	文章的原始内容	string
page.photos	文章的照片（用于相簿）	array
page.link	文章的外部链接（用于链接文章）	string

文章变量 (post)

与 page 布局相同，但新增以下变量。

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

三、特殊页面变量

首页(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）

辅助函数帮助您在模版中快速插入内容。不能在源文件中使用。

网址

url_for

在路径前加上根路径，从 Hexo 2.7 开始您应该使用此函数而不是 config.root + path。

<%- url_for(path, [option]) %>

参数	描述	默认值
relative	是否输出相对链接	config.relative_link 的值

示例：

_config.yml
root: /blog/

<%- url_for('/a/path') %>
// /blog/a/path

是否输出相对链接，默认遵循配置文件中 relative_link 的值。例如， post/page 的相对路径值可能是 /foo/bar/index.html

_config.yml
relative_link: true

<%- url_for('/css/style.css') %>
// ../../css/style.css
/* 覆盖配置
 * 即使配置文件中启用了 relative_link，你也可以使用 relative 参数禁用相对链接输出，反之亦然
 */
<%- url_for('/css/style.css', {relative: false}) %>
// /css/style.css

relative_url

取得与 from 相对的 to 路径。

<%- relative_url(from, to) %>

示例：

<%- relative_url('foo/bar/', 'css/style.css') %>
// ../../css/style.css

gravatar

根据邮箱地址返回 Gravatar 头像 URL。

如果你不指定 options 参数，将会应用默认参数。否则，你可以将其设置为一个数字，这个数字将会作为 Gravatar 的大小参数。最后，如果你设置它一个对象，它将会被转换为 Gravatar 的一个查询字符串参数。

<%- gravatar(email, [options]) %>

参数	描述	默认值
s	图片大小	80
d	默认头像
f	强制使用默认图象
r	头像等级限制

访问 Gravatar 了解更多。

示例：

<%- gravatar('[email protected]') %>
// https://www.gravatar.com/avatar/b9b00e66c6b8a70f88c73cb6bdb06787

<%- gravatar('[email protected]', 40) %>
// https://www.gravatar.com/avatar/b9b00e66c6b8a70f88c73cb6bdb06787?s=40

<%- gravatar('[email protected]' {s: 40, d: 'https://via.placeholder.com/150'}) %>
// https://www.gravatar.com/avatar/b9b00e66c6b8a70f88c73cb6bdb06787?s=40&d=https%3A%2F%2Fvia.placeholder.com%2F150

full_url_for

在路径前加上根路径和域名。输出会被自动转码。

<%- full_url_for(path) %>

示例：

_config.yml
url: https://example.com/blog # example

<%- full_url_for('/a/path') %>
// https://example.com/blog/a/path

HTML 标签

css

载入 CSS 文件。path 可以是数组或字符串，如果 path 开头不是 / 或任何协议，则会自动加上根路径；如果后面没有加上 .css 扩展名的话，也会自动加上。对于自定义属性请使用对象类型。

<%- css(path, ...) %>

示例：

<%- css('style.css') %>
// 

<%- css(['style.css', 'screen.css']) %>
// 
// 

<%- css({ href: 'style.css', integrity: 'foo' }) %>
// 

<%- css([{ href: 'style.css', integrity: 'foo' }, { href: 'screen.css', integrity: 'bar' }]) %>
// 
// 

js

载入 JavaScript 文件。path 可以是数组或字符串，如果 path 开头不是 / 或任何协议，则会自动加上根路径；如果后面没有加上 .js 扩展名的话，也会自动加上。对于自定义属性请使用对象类型。

<%- js(path, ...) %>

示例：

<%- js('script.js') %>
// 

<%- js(['script.js', 'gallery.js']) %>
// 
// 

<%- js({ src: 'script.js', integrity: 'foo', async: true }) %>
// 

<%- js([{ src: 'script.js', integrity: 'foo' }, { src: 'gallery.js', integrity: 'bar' }]) %>
// 
// 

link_to

插入链接。

<%- link_to(path, [text], [options]) %>

参数	描述	默认值
external	在新视窗打开链接	false
class	Class 名称
id	ID

示例：

<%- link_to('http://www.google.com') %>
// http://www.google.com

<%- link_to('http://www.google.com', 'Google') %>
// Google

<%- link_to('http://www.google.com', 'Google', {external: true}) %>
// Google

mail_to

插入电子邮箱链接。

<%- mail_to(path, [text], [options]) %>

参数	描述
class	Class 名称
id	ID
subject	邮件主题
cc	抄送（CC）
bcc	密送（BCC）
body	邮件内容

示例：

<%- mail_to('[email protected]') %>
// [email protected]

<%- mail_to('[email protected]', 'Email') %>
// Email

image_tag

插入图片。

<%- image_tag(path, [options]) %>

参数	描述
alt	图片的替代文字
class	Class 名称
id	ID
width	图片宽度
height	图片高度

favicon_tag

插入 favicon。

<%- favicon_tag(path) %>

feed_tag

插入 feed 链接。

<%- feed_tag(path, [options]) %>

参数	描述	默认值
title	Feed 标题	config.title
type	Feed 类型	atom

示例：

<%- feed_tag('atom.xml') %>
// 

<%- feed_tag('rss.xml', { title: 'RSS Feed', type: 'rss' }) %>
// 

/* Defaults to hexo-generator-feed's config if no argument */
<%- feed_tag() %>
// 

条件函数

is_current

检查 path 是否符合目前页面的网址。开启 strict 选项启用严格比对。

<%- is_current(path, [strict]) %>

is_home

检查当前页面是否为首页。

<%- is_home() %>

is_home_first_page (+6.3.0)

检查当前页面是否为首页的第一页。

<%- is_home_first_page() %>

is_post

检查当前页面是否为文章。

<%- is_post() %>

is_page

检查当前页面是否为独立页面。

<%- is_page() %>

is_archive

检查当前页面是否为存档页面。

<%- is_archive() %>

is_year

检查当前页面是否为年度归档页面。

<%- is_year() %>

is_month

检查当前页面是否为月度归档页面。

<%- is_month() %>

is_category

检查当前页面是否为分类归档页面。
如果给定一个字符串作为参数，将会检查目前是否为指定分类。

<%- is_category() %>
<%- is_category('hobby') %>

is_tag

检查当前页面是否为标签归档页面。
如果给定一个字符串作为参数，将会检查目前是否为指定标签。

<%- is_tag() %>
<%- is_tag('hobby') %>

字符串处理

trim

清除字符串开头和结尾的空格。

<%- trim(string) %>

strip_html

清除字符串中的 HTML 标签。

<%- strip_html(string) %>

示例：

<%- strip_html('It\'s not important anymore!') %>
// It's not important anymore!

titlecase

把字符串转换为正确的 Title case。

<%- titlecase(string) %>

示例：

<%- titlecase('this is an apple') %>
# This is an Apple

markdown

使用 Markdown 解析字符串。

<%- markdown(str) %>

示例：

<%- markdown('make me **strong**') %>
// make me strong

render

解析字符串。

<%- render(str, engine, [options]) %>

示例：

<%- render('p(class="example") Test', 'pug'); %>
// 
Test

详见 渲染。

word_wrap

使每行的字符串长度不超过 length。length 预设为 80。

<%- word_wrap(str, [length]) %>

示例：

<%- word_wrap('Once upon a time', 8) %>
// Once upon\n a time

truncate

移除超过 length 长度的字符串。length 的默认值是 30。

<%- truncate(text, length) %>

示例：

<%- truncate('Once upon a time in a world far far away', {length: 17}) %>
// Once upon a ti...

<%- truncate('Once upon a time in a world far far away', {length: 17, separator: ' '}) %>
// Once upon a...

<%- truncate('And they found that many people were sleeping better.', {length: 25, omission: '... (continued)'}) %>
// And they f... (continued)

escape_html

在字符串中转义 HTML 实体。

<%- escape_html(str) %>

示例：

<%- escape_html('
Hello "world".
') %>
// <p>Hello "world".</p>

模板

partial

载入其他模板文件，您可在 locals 设定区域变量。

<%- partial(layout, [locals], [options]) %>

参数	描述	默认值
cache	缓存（使用 Fragment cache）	false
only	限制局部变量。在模板中只能使用 locals 中设定的变量。	false

fragment_cache

局部缓存。它储存局部内容，下次使用时就能直接使用缓存。

<%- fragment_cache(id, fn);

示例：

<%- fragment_cache('header', function(){
  return '
';
}) %>

日期与时间

date

插入格式化的日期。date 可以是 UNIX 时间、ISO 字符串、Date 对象或 Moment.js 对象。format 默认为 date_format 配置信息。

<%- date(date, [format]) %>

示例：

<%- date(Date.now()) %>
// 2013-01-01

<%- date(Date.now(), 'YYYY/M/D') %>
// Jan 1 2013

date_xml

插入 XML 格式的日期。date 可以是 UNIX 时间、ISO 字符串、Date 对象或 Moment.js 对象。

<%- date_xml(date) %>

示例：

<%- date_xml(Date.now()) %>
// 2013-01-01T00:00:00.000Z

time

插入格式化的时间。date 可以是 UNIX 时间、ISO 字符串、Date 对象或 Moment.js 对象。format 默认为 time_format 配置信息。

<%- time(date, [format]) %>

示例：

<%- time(Date.now()) %>
// 13:05:12

<%- time(Date.now(), 'h:mm:ss a') %>
// 1:05:12 pm

full_date

插入格式化的日期和时间。date 可以是 UNIX 时间、ISO 字符串、Date 对象或 Moment.js 对象。format 默认为 date_format + time_format。

<%- full_date(date, [format]) %>

示例：

<%- full_date(new Date()) %>
// Jan 1, 2013 0:00:00

<%- full_date(new Date(), 'dddd, MMMM Do YYYY, h:mm:ss a') %>
// Tuesday, January 1st 2013, 12:00:00 am

moment

Moment.js 函数库。

列表

list_categories

插入分类列表。

<%- list_categories([options]) %>

参数	描述	默认值
orderby	分类排列方式	name
order	分类排列顺序。1, asc 升序；-1, desc 降序。	1
show_count	显示每个分类的文章总数	true
style	分类列表的显示方式。使用 list 以无序列表（unordered list）方式显示。	list
separator	分类间的分隔符号。只有在 style 不是 list 时有用。	,
depth	要显示的分类层级。0 显示所有层级的分类；-1 和 0 很类似，但是显示不分层级；1 只显示第一层的分类。	0
class	分类列表的 class 名称。	category
transform	改变分类名称显示方法的函数
suffix	为链接添加前缀	None

示例：

<%- list_categories(post.categories, {
  class: 'post-category',
  transform(str) {
    return titlecase(str);
  }
}) %>
 <%- list_categories(post.categories, {
  class: 'post-category',
  transform(str) {
    return str.toUpperCase();
  }
}) %>

list_tags

插入标签列表。

<%- list_tags([options]) %>

选项	描述	预设值
orderby	标签排列方式	name
order	标签排列顺序。1, asc 升序；-1, desc 降序。	1
show_count	显示每个标签的文章总数	true
style	标签列表的显示方式。使用 list 以无序列表（unordered list）方式显示。	list
separator	标签间的分隔符号。只有在 style 不是 list 时有用。	,
class	标签列表的类名（字符串）或自定义每个标签的类（对象，见下文）。	tag
transform	改变标签名称显示方法的函数。请查看 list_categories 中给出的例子
amount	要显示的标签数量（0 = 无限制）	0
suffix	为链接添加前缀	None

类的高级定制：

选项	描述	预设值
class.ul	类名 （只适用于样式 list）	tag-list （列表样式）
class.li	类名 （只适用于样式 list）	tag-list-item （列表样式）
class.a	类名	tag-list-link （列表样式） tag-link （普通样式）
class.label	类名，标签 label 存储在这里（仅适用于普通样式，当 class.label 被设置时，标签被放置在 中）	tag-label （普通样式）
class.count	类名，标签 counter 存储在这里 （仅当 show_count 为 true）	tag-list-count （列表样式） tag-count （普通样式）

示例：

<%- list_tags(site.tags, {class: 'classtest', style: false, separator: ' | '}) %>
<%- list_tags(site.tags, {class: 'classtest', style: 'list'}) %>
<%- list_tags(site.tags, {class: {ul: 'ululul', li: 'lilili', a: 'aaa', count: 'ccc'}, style: false, separator: ' | '}) %>
<%- list_tags(site.tags, {class: {ul: 'ululul', li: 'lilili', a: 'aaa', count: 'ccc'}, style: 'list'}) %>

list_archives

插入归档列表。

<%- list_archives([options]) %>

参数	描述	默认值
type	类型。此设定可为 yearly 或 monthly。	monthly
order	排列顺序。1, asc 升序；-1, desc 降序。	1
show_count	显示每个归档的文章总数	true
format	日期格式	MMMM YYYY
style	归档列表的显示方式。使用 list 以无序列表（unordered list）方式显示。	list
separator	归档间的分隔符号。只有在 style 不是 list 时有用。	,
class	归档列表的 class 名称。	archive
transform	改变归档名称显示方法的函数。请查看 list_categories 中给出的例子

list_posts

插入文章列表。

<%- list_posts([options]) %>

参数	描述	默认值
orderby	文章排列方式	date
order	文章排列顺序。1, asc 升序；-1, desc 降序。	-1
style	文章列表的显示方式。使用 list 以无序列表（unordered list）方式显示。	list
separator	文章间的分隔符号。只有在 style 不是 list 时有用。	,
class	文章列表的 class 名称。	post
amount	要显示的文章数量（0 = 无限制）	6
transform	改变文章名称显示方法的函数。请查看 list_categories 中给出的例子

tagcloud

插入标签云。

<%- tagcloud([tags], [options]) %>

参数	描述	默认值
min_font	最小字体尺寸	10
max_font	最大字体尺寸	20
unit	字体尺寸的单位	px
amount	标签总量	40
orderby	标签排列方式	name
order	标签排列顺序。1, sac 升序；-1, desc 降序	1
color	使用颜色	false
start_color	开始的颜色。您可使用十六进位值（#b700ff），rgba（rgba(183, 0, 255, 1)），hsla（hsla(283, 100%, 50%, 1)）或 颜色关键字。此变量仅在 color 参数开启时才有用。
end_color	结束的颜色。您可使用十六进位值（#b700ff），rgba（rgba(183, 0, 255, 1)），hsla（hsla(283, 100%, 50%, 1)）或 颜色关键字。此变量仅在 color 参数开启时才有用。
class	标签的 class name 前缀
level	不同 class name 的总数。此变量仅在 class 参数设定时才有用。	10
show_count (+6.3.0)	显示每个标签的文章总数	false
count_class (+6.3.0)	标签文章总数的 class	count

其他

paginator

插入分页链接。

<%- paginator(options) %>

参数	描述	默认值
base	基础网址	/
format	网址格式	page/%d/
total	分页总数	1
current	目前页数	0
prev_text	上一页链接的文字。仅在 prev_next 设定开启时才有用。	Prev
next_text	下一页链接的文字。仅在 prev_next 设定开启时才有用。	Next
space	空白文字	…
prev_next	显示上一页和下一页的链接	true
end_size	显示于两侧的页数	1
mid_size	显示于中间的页数	2
show_all	显示所有页数。如果开启此参数的话，end_size 和 mid_size 就没用了。	false
escape	转义 HTML 标签	true
page_class	分页链接的 class 名称	page-number
current_class (+6.3.0)	当前页链接的 class 名称	current
space_class (+6.3.0)	空白文字的 class 名称	space
prev_class (+6.3.0)	上一页链接的 class 名称	extend prev
next_class (+6.3.0)	下一页链接的 class 名称	extend next
force_prev_next (+6.3.0)	强制显示上一页和下一页的链接	false

示例：

<%- paginator({
  prev_text: '<',
  next_text: '>'
}) %>

<a href="/1/"><a>
<a href="/1/">1a>
2
<a href="/3/">3a>
<a href="/3/">>a>

<%- paginator({
  prev_text: '',
  next_text: '',
  escape: false
}) %>

<a href="/1/"><i class="fa fa-angle-left">i>a>
<a href="/1/">1a>
2
<a href="/3/">3a>
<a href="/3/"><i class="fa fa-angle-right">i>a>

search_form

插入 Google 搜索框。

<%- search_form(options) %>

参数	描述	默认值
class	表单的 class name	search-form
text	搜索提示文字	Search
button	显示搜索按钮。此参数可为布尔值（boolean）或字符串，当设定是字符串的时候，即为搜索按钮的文字。	false

number_format

格式化数字。

<%- number_format(number, [options]) %>

参数	描述	默认值
precision	数字精度。此选项可为 false 或非负整数。	false
delimiter	千位数分隔符号	,
separator	整数和小数之间的分隔符号	.

示例：

<%- number_format(12345.67, {precision: 1}) %>
// 12,345.68

<%- number_format(12345.67, {precision: 4}) %>
// 12,345.6700

<%- number_format(12345.67, {precision: 0}) %>
// 12,345

<%- number_format(12345.67, {delimiter: ''}) %>
// 12345.67

<%- number_format(12345.67, {separator: '/'}) %>
// 12,345/67

meta_generator

插入 generator tag。

<%- meta_generator() %>

示例：

<%- meta_generator() %>
// 

open_graph

插入 open graph 资源。

<%- open_graph([options]) %>

参数	描述	默认值
title	页面标题 (og:title)	page.title
type	页面类型 (og:type)	blog
url	页面网址 (og:url)	url
image	页面图片 (og:image)	内容中的图片
author	文章作者 (og:article:author)	config.author
date	文章发表时间 (og:article:published_time)	页面发表时间
updated	文章修改时间 (og:article:modified_time)	页面修改时间
language	文章语言 (og:locale)	`page.lang
site_name	网站名称 (og:site_name)	config.title
description	页面描述 (og:description)	内容摘要或前 200 字
twitter_card	Twitter 卡片类型 (twitter:card)	summary
twitter_id	Twitter ID (twitter:creator)
twitter_site	Twitter 网站 (twitter:site)
google_plus	Google+ 个人资料链接
fb_admins	Facebook 管理者 ID
fb_app_id	Facebook 应用程序 ID

toc

解析内容中的标题标签 (h1~h6) 并插入目录。

<%- toc(str, [options]) %>

参数	描述	默认值
class	Class 名称	toc
class_item (+6.3.0)	目录元素的 Class 名称	${class}-item
class_link (+6.3.0)	目录内链接的 Class 名称	${class}-link
class_text (+6.3.0)	目录链接内文本的 Class 名称	${class}-text
class_child (+6.3.0)	目录内子列表的 Class 名称	${class}-child
class_number (+6.3.0)	目录序号的 Class 名称	${class}-number
class_level	目录层级的 Class 名称前缀	${class}-level
list_number	显示编号	true
max_depth	生成 TOC 的最大深度	6
min_depth	生成 TOC 的最小深度	1

示例：

<%- toc(page.content) %>

data-toc-unnumbered (+6.1.0)

带有 data-toc-unnumbered="true" 属性的标题将被标记为未编号（不显示列表编号）。

{% note warn “警告！” %}
对于使用 data-toc-unnumbered="true"，渲染引擎必须要有添加 CSS 类的选项。

请看下面的 PR。

• https://github.com/hexojs/hexo/pull/4871
• https://github.com/hexojs/hexo-util/pull/269
• https://github.com/hexojs/hexo-renderer-markdown-it/pull/174
  {% endnote %}