輔助函數（Helpers）

輔助函數幫助您在模版中快速插入內容。

網址

url_for

在路徑前加上根路徑，從 Hexo 2.7 開始您應該使用此函數，避免使用 config.root + path。

<%- url_for(path) %>

relative_url

取得與 from 相對的 to 路徑。

<%- relative_url(from, to) %>

gravatar

插入 Gravatar 圖片。

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

範例：

<%- gravatar('a@abc.com') %>
// https://www.gravatar.com/avatar/b9b00e66c6b8a70f88c73cb6bdb06787

<%- gravatar('a@abc.com', 40) %>
// https://www.gravatar.com/avatar/b9b00e66c6b8a70f88c73cb6bdb06787?s=40

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

HTML 標籤

css

載入 CSS 檔案。path 可以是陣列或字串，如果 path 開頭不是 / 或任何協議，則會自動加上根路徑；如果後面沒有加上 .css 副檔名的話，也會自動加上。Use object type for custom attributes.

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

範例：

<%- css('style.css') %>
// <link rel="stylesheet" href="/style.css">

<%- css(['style.css', 'screen.css']) %>
// <link rel="stylesheet" href="/style.css">
// <link rel="stylesheet" href="/screen.css">

<%- css({ href: 'style.css', integrity: 'foo' }) %>
// <link rel="stylesheet" href="/style.css" integrity="foo">

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

js

載入 JavaScript 檔案。path 可以是陣列或字串，如果 path 開頭不是 / 或任何協議，則會自動加上根路徑；如果後面沒有加上 .js 副檔名的話，也會自動加上。Use object type for custom attributes.

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

範例：

<%- js('script.js') %>
// <script src="/script.js"></script>

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

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

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

link_to

插入連結。

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

選項	描述	預設值
external	在新視窗開啟連結	false
class	Class 名稱
id	ID

範例：

<%- link_to('http://www.google.com') %>
// <a href="http://www.google.com" title="http://www.google.com">http://www.google.com</a>

<%- link_to('http://www.google.com', 'Google') %>
// <a href="http://www.google.com" title="Google">Google</a>

<%- link_to('http://www.google.com', 'Google', {external: true}) %>
// <a href="http://www.google.com" title="Google" target="_blank" rel="noopener">Google</a>

mail_to

插入電子郵件連結。

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

選項	描述
class	Class 名稱
id	ID
subject	郵件主旨
cc	副本（CC）
bcc	密件副本（BCC）
body	郵件內容

範例：

<%- mail_to('a@abc.com') %>
// <a href="mailto:a@abc.com" title="a@abc.com">a@abc.com</a>

<%- mail_to('a@abc.com', 'Email') %>
// <a href="mailto:a@abc.com" title="Email">Email</a>

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 類型

範例：

<%- feed_tag('atom.xml') %>
// <link rel="alternate" href="/atom.xml" title="Hexo" type="application/atom+xml">

<%- feed_tag('rss.xml', { title: 'RSS Feed', type: 'rss' }) %>
// <link rel="alternate" href="/atom.xml" title="RSS Feed" type="application/rss+xml">

/* Defaults to hexo-generator-feed's config if no argument */
<%- feed_tag() %>
// <link rel="alternate" href="/atom.xml" title="Hexo" type="application/atom+xml">

判斷函數

is_current

檢查 path 是否符合目前頁面的網址。開啟 strict 選項啟用嚴格比對。

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

is_home

檢查目前是否為首頁。

<%- is_home() %>

is_post

檢查目前是否為文章。

<%- is_post() %>

is_archive

檢查目前是否為彙整頁面。

<%- is_archive() %>

is_year

檢查目前是否為年度彙整頁面。

<%- is_year() %>

is_month

檢查目前是否為每月彙整頁面。

<%- is_month() %>

is_category

檢查目前是否為分類彙整頁面。

<%- is_category() %>

is_tag

檢查目前是否為標籤彙整頁面。

<%- is_tag() %>

字串處理

trim

清除字串的開頭和結尾空白。

<%- trim(string) %>

strip_html

清除字串中的 HTML 標籤。

<%- strip_html(string) %>

範例：

<%- strip_html('It\'s not <b>important</b> 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>strong</strong>

render

渲染字串。

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

Examples:

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

See Rendering for more details.

word_wrap

使每行的字串長度不超過 length。length 預設為 80。

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

範例：

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

truncate

移除超過 length 的字串。

<%- truncate(text, length) %>

範例：

<%- truncate('Once upon a time in a world far far away', 16) %>
// Once upon a time

escape_html

Escapes HTML entities in a string.

<%- escape_html(str) %>

Examples:

<%- escape_html('<p>Hello "world".</p>') %>
// &lt;p&gt;Hello &quot;world&quot;.&lt;&#x2F;p&gt;

模板

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()) %>
// 2013-01-01

<%- date(Date.now(), 'MMM D YYYY') %>
// 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

relative_date

Inserts relative time from now. date can be unix time, ISO string, date object, or Moment.js object.

<%- relative_date(date) %>

Examples:

<%- relative_date(new Date()) %>
// a few seconds ago

<%- relative_date(new Date(1000000000000)) %>
// 22 years ago

time_tag

Inserts time tag. date can be unix time, ISO string, date object, or Moment.js object. format is date_format setting by default.

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

Examples:

<%- time_tag(new Date()) %>
// <time datetime="2024-01-22T06:35:31.108Z">2024-01-22</time>

<%- time_tag(new Date(), 'MMM-D-YYYY') %>
// <time datetime="2024-01-22T06:35:31.108Z">Jan-22-2024</time>

moment

Moment.js 函式庫。

列表

list_categories

插入分類列表。

<%- list_categories([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	改變分類名稱顯示方法的函數

list_tags

插入標籤列表。

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

選項	描述	預設值
orderby	標籤排列方式	name
order	標籤排列順序。1, asc 升冪；-1, desc 降冪。	1
show_count	顯示每個標籤的文章總數	true
style	標籤列表的顯示方式。使用 list 以無序列表（unordered list）方式顯示。	list
separator	標籤間的分隔符號。只有在 style 不是 list 時有用。	,
class	Class name of tag list (string) or customize each tag’s class (object, see below).	tag
transform	改變標籤名稱顯示方法的函數
amount	要顯示的標籤數量（0 = 無限制）	0
suffix	Add a suffix to link.	None

Class advanced customization:

Option	Description	Default
class.ul	<ul> class name (only for style list)	tag-list (list style)
class.li	<li> class name (only for style list)	tag-list-item (list style)
class.a	<a> class name	tag-list-link (list style) tag-link (normal style)
class.label	<span> class name where the tag label is stored (only for normal style, when class.label is set the label is put in a <span>)	tag-label (normal style)
class.count	<span> class name where the tag counter is stored (only when show_count is true)	tag-list-count (list style) tag-count (normal style)

Examples:

<%- 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_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	改變文章名稱顯示方法的函數

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 prefix of tags
level	不同 class name 的總數。此選項僅在 class 設定時才有用。	10

其他

paginator

插入分頁連結。

<%- paginator(options) %>

選項	描述	預設值
base	基礎網址	/
format	網址格式	page/%d/
total	分頁總數	1
current	目前頁數	0
prev_text	上一頁連結的文字。僅在 prev_next 設定開啟時才有用。	Prev
next_text	下一頁連結的文字。僅在 prev_next 設定開啟時才有用。	Next
space	空白文字	&hellp;
prev_next	顯示上一頁和下一頁的連結	true
end_size	顯示於兩側的頁數	1
mid_size	顯示於中間的頁數	2
show_all	顯示所有頁數。如果開啟此設定的話，end_size 和 mid_size 就沒用了。	false
escape	Escape HTML tags	true

Examples:

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

<!-- Rendered as -->
<a href="/1/">&lt;</a>
<a href="/1/">1</a>
2
<a href="/3/">3</a>
<a href="/3/">&gt;</a>

<%- paginator({
  prev_text: '<i class="fa fa-angle-left"></i>',
  next_text: '<i class="fa fa-angle-right"></i>',
  escape: false
}) %>

<!-- Rendered as -->
<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}) %>
// 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

Inserts generator tag.

<%- meta_generator() %>

Examples:

<%- meta_generator() %>
// <meta name="generator" content="Hexo 4.0.0">

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	Article author (og:article:author)	config.author
date	Article published time (og:article:published_time)	Page published time
updated	Article modified time (og:article:modified_time)	Page modified time
language	Article 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
list_number	顯示編號	true
max_depth	生成 TOC 的最大深度	6
min_depth	生成 TOC 的最小深度	1

範例：

<%- toc(page.content) %>

data-toc-unnumbered (+6.1.0)

Headings with attribute data-toc-unnumbered="true" will be marked as unnumbered (list number will not be display).

Warning!

For using data-toc-unnumbered="true", the renderer must have the option to add CSS classes.

Please see below PRs.

• 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