辅助函数帮助您在模版中快速插入内容。辅助函数不能在源文件中使用。
网址
url_for
在路径前加上根路径，从 Hexo 2.7 开始您应该使用此函数而不是 config.root + path。
<%- url_for(path, [option]) %>
|
| 参数 |
描述 |
默认值 |
relative |
是否输出相对链接 |
config.relative_link 的值 |
示例：
<%- url_for('/a/path') %>
|
是否输出相对链接，默认遵循配置文件中 relative_link 的值
例如， post/page 的相对路径值可能是 /foo/bar/index.html
_config.yml
relative_link: true
|
<%- url_for('/css/style.css') %>
<%- url_for('/css/style.css', {relative: false}) %>
|
relative_url
取得与 from 相对的 to 路径。
<%- relative_url(from, to) %>
|
示例：
<%- relative_url('foo/bar/', 'css/style.css') %>
|
gravatar
根据邮箱地址返回 Gravatar 头像 URL。
如果你不指定 options 参数，将会应用默认参数。否则，你可以将其设置为一个数字，这个数字将会作为 Gravatar 的大小参数。最后，如果你设置它一个对象，它将会被转换为 Gravatar 的一个查询字符串参数。
<%- gravatar(email, [options]) %>
|
| 参数 |
描述 |
默认值 |
s |
图片大小 |
80 |
d |
默认头像 |
|
f |
强制使用默认图象 |
|
r |
头像等级限制 |
|
访问 Gravatar 了解更多。
示例：
<%- gravatar('a@abc.com') %>
<%- gravatar('a@abc.com', 40) %>
<%- gravatar('a@abc.com' {s: 40, d: 'https://via.placeholder.com/150'}) %>
|
full_url_for
在路径前加上根路径和域名。输出会被自动转码。
<%- full_url_for(path) %>
|
示例：
_config.yml
url: https://example.com/blog
|
<%- full_url_for('/a/path') %>
|
HTML 标签
css
加载 CSS 文件。path 可以是数组或字符串，如果 path 开头不是 / 或任何协议，则会自动加上根路径；如果后面没有加上 .css 扩展名的话，也会自动加上。对于自定义属性请使用对象类型。
示例：
<%- 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('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') %>
<%- link_to('http://www.google.com', 'Google') %>
<%- link_to('http://www.google.com', 'Google', {external: true}) %>
|
mail_to
插入电子邮箱链接。
<%- mail_to(path, [text], [options]) %>
|
| 参数 |
描述 |
class |
Class 名称 |
id |
ID |
subject |
邮件主题 |
cc |
抄送（CC） |
bcc |
密送（BCC） |
body |
邮件内容 |
示例：
<%- mail_to('a@abc.com') %>
<%- mail_to('a@abc.com', 'Email') %>
|
image_tag
插入图片。
<%- image_tag(path, [options]) %>
|
| 参数 |
描述 |
alt |
图片的替代文字 |
class |
Class 名称 |
id |
ID |
width |
图片宽度 |
height |
图片高度 |
favicon_tag
插入 favicon。
feed_tag
插入 feed 链接。
<%- feed_tag(path, [options]) %>
|
| 参数 |
描述 |
默认值 |
title |
Feed 标题 |
config.title |
type |
Feed 类型 |
|
示例：
<%- feed_tag('atom.xml') %>
<%- feed_tag('rss.xml', { title: 'RSS Feed', type: 'rss' }) %>
<%- feed_tag() %>
|
条件函数
is_current
检查 path 是否符合目前页面的网址。开启 strict 选项启用严格比对。
<%- is_current(path, [strict]) %>
|
is_home
检查当前页面是否为首页。
is_home_first_page (+6.3.0)
检查当前页面是否为首页的第一页。
<%- is_home_first_page() %>
|
is_post
检查当前页面是否为文章。
is_page
检查当前页面是否为独立页面。
is_archive
检查当前页面是否为存档页面。
is_year
检查当前页面是否为年度归档页面。
is_month
检查当前页面是否为月度归档页面。
is_category
检查当前页面是否为分类归档页面。
如果给定一个字符串作为参数，将会检查目前是否为指定分类。
<%- is_category() %>
<%- is_category('hobby') %>
|
is_tag
检查当前页面是否为标签归档页面。
如果给定一个字符串作为参数，将会检查目前是否为指定标签。
<%- is_tag() %>
<%- is_tag('hobby') %>
|
字符串处理
trim
清除字符串开头和结尾的空格。
strip_html
清除字符串中的 HTML 标签。
<%- strip_html(string) %>
|
示例：
<%- strip_html('It\'s not <b>important</b> anymore!') %>
|
titlecase
把字符串转换为正确的 Title case。
示例：
<%- titlecase('this is an apple') %>
# This is an Apple
|
markdown
使用 Markdown 解析字符串。
示例：
<%- markdown('make me **strong**') %>
|
render
解析字符串。
<%- render(str, engine, [options]) %>
|
示例：
<%- render('p(class="example") Test', 'pug'); %>
|
详见 渲染。
word_wrap
使每行的字符串长度不超过 length。length 预设为 80。
<%- word_wrap(str, [length]) %>
|
示例：
<%- word_wrap('Once upon a time', 8) %>
|
truncate
移除超过 length 长度的字符串。length 的默认值是 30。
<%- truncate(text, length) %>
|
示例：
<%- truncate('Once upon a time in a world far far away', {length: 17}) %>
<%- truncate('Once upon a time in a world far far away', {length: 17, separator: ' '}) %>
<%- truncate('And they found that many people were sleeping better.', {length: 25, omission: '... (continued)'}) %>
|
escape_html
在字符串中转义 HTML 实体。
示例：
<%- escape_html('<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 '<header></header>';
}) %>
|
日期与时间
date
插入格式化的日期。date 可以是 UNIX 时间、ISO 字符串、Date 对象或 Moment.js 对象。format 默认为 date_format 配置信息。
<%- date(date, [format]) %>
|
示例：
<%- date(Date.now()) %>
<%- date(Date.now(), 'YYYY/M/D') %>
|
date_xml
插入 XML 格式的日期。date 可以是 UNIX 时间、ISO 字符串、Date 对象或 Moment.js 对象。
示例：
<%- date_xml(Date.now()) %>
|
time
插入格式化的时间。date 可以是 UNIX 时间、ISO 字符串、Date 对象或 Moment.js 对象。format 默认为 time_format 配置信息。
<%- time(date, [format]) %>
|
示例：
<%- time(Date.now()) %>
<%- time(Date.now(), 'h:mm:ss a') %>
|
full_date
插入格式化的日期和时间。date 可以是 UNIX 时间、ISO 字符串、Date 对象或 Moment.js 对象。format 默认为 date_format + time_format。
<%- full_date(date, [format]) %>
|
示例：
<%- full_date(new Date()) %>
<%- full_date(new Date(), 'dddd, MMMM Do YYYY, h:mm:ss a') %>
|
relative_date
插入相对当前的时间。date 可以是 UNIX 时间、ISO 字符串、Date 对象或 Moment.js 对象。
<%- relative_date(date) %>
|
示例：
<%- relative_date(new Date()) %>
<%- relative_date(new Date(1000000000000)) %>
|
time_tag
插入时间标签。date 可以是 UNIX 时间、ISO 字符串、Date 对象或 Moment.js 对象。format 默认为 date_format 配置信息。
<%- time_tag(date, [format]) %>
|
示例：
<%- time_tag(new Date()) %>
<%- time_tag(new Date(), 'MMM-D-YYYY') %>
|
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 |
<ul> 类名 （只适用于样式 list） |
tag-list （列表样式） |
class.li |
<li> 类名 （只适用于样式 list） |
tag-list-item （列表样式） |
class.a |
<a> 类名 |
tag-list-link （列表样式） tag-link （普通样式） |
class.label |
<span> 类名，标签 label 存储在这里（仅适用于普通样式，当 class.label 被设置时，标签被放置在 <span> 中） |
tag-label （普通样式） |
class.count |
<span> 类名，标签 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/">1</a>
2
<a href="/3/">3</a>
<a href="/3/">></a>
|
<%- paginator({
prev_text: '<i class="fa fa-angle-left"></i>',
next_text: '<i class="fa fa-angle-right"></i>',
escape: false
}) %>
|
<a href="/1/"><i class="fa fa-angle-left"></i></a>
<a href="/1/">1</a>
2
<a href="/3/">3</a>
<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}) %>
<%- number_format(12345.67, {precision: 4}) %>
<%- number_format(12345.67, {precision: 0}) %>
<%- number_format(12345.67, {delimiter: ''}) %>
<%- number_format(12345.67, {separator: '/'}) %>
|
meta_generator
插入 generator tag。
示例：
open_graph
插入 open graph 资源。
<%- open_graph([options]) %>
|
| 参数 |
描述 |
默认值 |
title |
页面标题 (og:title) |
page.title |
type |
页面类型 (og:type) |
article(post page)
website(non-post page) |
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 || page.language || config.language |
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) |
|
twitter_image |
Twitter 图片 (twitter:image) |
|
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 |
示例：
data-toc-unnumbered (+6.1.0)
带有 data-toc-unnumbered="true" 属性的标题将被标记为未编号（不显示列表编号）。
警告！对于使用 data-toc-unnumbered="true"，渲染引擎必须要有添加 CSS 类的选项。
请看下面的 PR。