輔助函數

輔助函數在模板中用於快速插入程式碼片段。輔助函數不能在原始檔案中使用。

您可以輕鬆編寫自己的自訂輔助函數或使用我們現成的輔助函數。

URL

url_for

返回一個帶有根路徑前綴的 URL。輸出會自動編碼。

<%- url_for(path, [option]) %>
選項 描述 預設值
relative 輸出相對連結 config.relative_link 的值

範例

_config.yml
root: /blog/ # example
<%- url_for('/a/path') %>
// /blog/a/path

相對連結，預設跟隨 relative_link 選項
例如，文章/頁面路徑為「/foo/bar/index.html」

_config.yml
relative_link: true
<%- url_for('/css/style.css') %>
// ../../css/style.css

/* Override option
 * you could also disable it to output a non-relative link,
 * even when `relative_link` is enabled and vice versa.
 */
<%- url_for('/css/style.css', {relative: false}) %>
// /css/style.css

relative_url

返回從 from 到 to 的相對 URL。

<%- relative_url(from, to) %>

範例

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

full_url_for

返回一個帶有 config.url 前綴的 URL。輸出會自動編碼。

<%- full_url_for(path) %>

範例

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

gravatar

從電子郵件返回 Gravatar 圖像 URL。

如果您沒有指定 [options] 參數，則會套用預設選項。否則，您可以將其設定為一個數字，然後將其作為大小參數傳遞給 Gravatar。最後，如果您將其設定為物件，它將被轉換為 Gravatar 的參數查詢字串。

<%- gravatar(email, [options]) %>
選項 描述 預設值
s 輸出圖像大小 80
d 預設圖像
f 強制使用預設值
r 評級

更多資訊：Gravatar

範例

<%- 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 副檔名時，會預先加入 /<root>/ 值。使用物件類型進行自訂屬性。

<%- 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 副檔名時，會預先加入 /<root>/ 值。使用物件類型進行自訂屬性。

<%- 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 類別名稱
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 類別名稱
id ID
subject 郵件主旨
cc 副本
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 類別名稱
id ID
width 圖像寬度
height 圖像高度

favicon_tag

插入網站圖示。

<%- favicon_tag(path) %>

feed_tag

插入訂閱連結。

<%- feed_tag(path, [options]) %>
選項 描述 預設值
title 訂閱標題 config.title
type 訂閱類型

範例

<%- 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/atom+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 是否與目前頁面的 URL 相符。使用 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 <b>important</b> anymore!') %>
// It's not important anymore!

titlecase

將字串轉換為正確的標題大寫。

<%- 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]) %>

範例

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

有關更多詳細資訊，請參閱渲染。

word_wrap

將文字換行，使其長度不超過 length。預設情況下，length 為 80。

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

範例

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

truncate

在特定 length 後截斷文字。預設為 30 個字元。

<%- truncate(text, [options]) %>

範例

<%- 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('<p>Hello "world".</p>') %>
// &lt;p&gt;Hello &quot;world&quot;.&lt;&#x2F;p&gt;

模板

partial

載入其他模板檔案。您可以在 locals 中定義局部變數。

<%- partial(layout, [locals], [options]) %>
選項 描述 預設值
cache 快取內容 (使用片段快取) false
only 嚴格局部變數。僅在模板中使用 locals 中設定的變數。 false

fragment_cache

快取片段中的內容。它會在片段中儲存內容，並在下一個請求進入時提供快取。

<%- fragment_cache(id, fn);

範例

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

日期 & 時間

date

插入格式化的日期。date 可以是 Unix 時間、ISO 字串、日期物件或 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 字串、日期物件或 Moment.js 物件。

<%- date_xml(date) %>

範例

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

time

插入格式化的時間。date 可以是 Unix 時間、ISO 字串、日期物件或 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 字串、日期物件或 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

插入從現在開始的相對時間。date 可以是 Unix 時間、ISO 字串、日期物件或 Moment.js 物件。

<%- relative_date(date) %>

範例

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

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

time_tag

插入時間標籤。date 可以是 Unix 時間、ISO 字串、日期物件或 Moment.js 物件。預設情況下，format 是 date_format 設定。

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

範例

<%- 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([options]) %>
選項 描述 預設值
orderby 分類的排序 name
order 排序方式。1, asc 為升序；-1, desc 為降序 1
顯示計數 顯示每個分類的文章數量 true
樣式 顯示分類列表的樣式。list 以無序列表顯示分類。使用 false 或任何其他值來停用它。 list
分隔符 分類之間的分隔符。（僅在 style 不是 list 時有效） ,
深度 要顯示的分類層級。0 顯示所有分類和子分類；-1 與 0 類似，但以扁平方式顯示；1 僅顯示頂層分類。 0
class 分類列表的 CSS 類別名稱。 category
轉換 更改分類名稱顯示方式的函式。
後綴 為連結添加後綴。 無

範例

<%- 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
顯示計數 顯示每個標籤的文章數量 true
樣式 顯示標籤列表的樣式。list 以無序列表顯示標籤。使用 false 或任何其他值來停用它。 list
分隔符 分類之間的分隔符。（僅在 style 不是 list 時有效） ,
class 標籤列表的類別名稱（字串）或自訂每個標籤的類別（物件，請參閱下方）。 tag
轉換 更改標籤名稱顯示方式的函式。請參閱 list_categories 中的範例。
數量 要顯示的標籤數量（0 = 無限制） 0
後綴 為連結添加後綴。 無

類別進階自訂

選項 描述 預設值
class.ul <ul> 類別名稱（僅適用於樣式 list） tag-list (列表樣式)
class.li <li> 類別名稱（僅適用於樣式 list） tag-list-item (列表樣式)
class.a <a> 類別名稱 tag-list-link (列表樣式) tag-link (一般樣式)
class.label 儲存標籤標籤的 <span> 類別名稱（僅適用於一般樣式，當設定 class.label 時，標籤會放在 <span> 中） tag-label (一般樣式)
class.count 儲存標籤計數器的 <span> 類別名稱（僅在 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
顯示計數 顯示每個封存的文章數量 true
格式 日期格式 MMMM YYYY
樣式 顯示封存列表的樣式。list 以無序列表顯示封存。使用 false 或任何其他值來停用它。 list
分隔符 封存之間的分隔符。（僅在 style 不是 list 時有效） ,
class 封存列表的類別名稱。 archive
轉換 更改封存名稱顯示方式的函式。請參閱 list_categories 中的範例。

list_posts

插入文章列表。

<%- list_posts([options]) %>
選項 描述 預設值
orderby 文章的排序方式 date
order 排序方式。1, asc 為升序；-1, desc 為降序 1
樣式 顯示文章列表的樣式。list 以無序列表顯示文章。使用 false 或任何其他值來停用它。 list
分隔符 文章之間的分隔符。（僅在 style 不是 list 時有效） ,
class 文章列表的類別名稱。 post
數量 要顯示的文章數量（0 = 無限制） 6
轉換 更改文章名稱顯示方式的函式。請參閱 list_categories 中的範例。

tagcloud

插入標籤雲。

<%- tagcloud([tags], [options]) %>
選項 描述 預設值
min_font 最小字體大小 10
max_font 最大字體大小 20
單位 字體大小單位 px
數量 標籤總數 無限制
orderby 標籤的排序方式 name
order 排序方式。1, asc 為升序；-1, desc 為降序 1
色彩 為標籤雲著色 false
start_color 起始顏色。您可以使用十六進制碼 (#b700ff)、rgba (rgba(183, 0, 255, 1))、hsla (hsla(283, 100%, 50%, 1)) 或 顏色關鍵字。此選項僅在 color 為 true 時有效。
end_color 結束顏色。您可以使用十六進制碼 (#b700ff)、rgba (rgba(183, 0, 255, 1))、hsla (hsla(283, 100%, 50%, 1)) 或 顏色關鍵字。此選項僅在 color 為 true 時有效。
class 標籤的類別名稱前綴
層級 不同類別名稱的數量。此選項僅在設定 class 時有效。 10
顯示計數 (+6.3.0) 顯示每個標籤的文章數量 false
count_class (+6.3.0) 標籤計數的類別名稱 count

範例

// Default options
<%- tagcloud() %>

// Limit number of tags to 30
<%- tagcloud({amount: 30}) %>

雜項

分頁器

插入分頁器。

<%- paginator(options) %>
選項 描述 預設值
基礎 基礎網址 /
格式 網址格式 page/%d/
總數 頁數 1
當前 當前頁碼 0
prev_text 上一頁的連結文字。僅在 prev_next 設定為 true 時有效。 上一頁
next_text 下一頁的連結文字。僅在 prev_next 設定為 true 時有效。 下一頁
間隔 間隔文字 &hellp;
prev_next 顯示上一頁和下一頁連結 true
end_size 在開頭和結尾顯示的頁面數量 1
mid_size 在當前頁面之間顯示的頁面數量，但不包括當前頁面 2
show_all 顯示所有頁面。如果此設定為 true，則 end_size 和 mid_size 將不起作用 false
escape 跳脫 HTML 標籤 true
page_class (+6.3.0) 頁面類別名稱 page-number
current_class (+6.3.0) 當前頁面類別名稱 當前
space_class (+6.3.0) 間隔類別名稱 間隔
prev_class (+6.3.0) 上一頁類別名稱 延伸上一頁
next_class (+6.3.0) 下一頁類別名稱 延伸下一頁
force_prev_next (+6.3.0) 強制顯示上一頁和下一頁連結 false

範例

<%- 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 表單的類別名稱 search-form
text 搜尋提示文字 搜尋
button 顯示搜尋按鈕。值可以是布林值或字串。如果值是字串，則將作為按鈕的文字。 false

number_format

格式化數字。

<%- number_format(number, [options]) %>
選項 描述 預設值
精確度 數字的精確度。值可以是 false 或非負整數。 false
分隔符 千位分隔符 ,
分隔符 小數和整數數字之間的分隔符。 .

範例

<%- 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 標籤。

<%- meta_generator() %>

範例

<%- 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(文章頁面)
website(非文章頁面)
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 類別名稱 toc
class_item (+6.3.0) 項目的類別名稱 ${class}-item
class_link (+6.3.0) 連結的類別名稱 ${class}-link
class_text (+6.3.0) 文字的類別名稱 ${class}-text
class_child (+6.3.0) 子項目的類別名稱 ${class}-child
class_number (+6.3.0) 數字的類別名稱 ${class}-number
class_level (+6.3.0) 層級的類別名稱前綴 ${class}-level
list_number 顯示列表編號 true
max_depth 產生的目錄的最大標題深度 6
min_depth 產生的目錄的最小標題深度 1
max_items (+7.3.0) 產生的目錄中的最大項目數 無限大

範例

<%- toc(page.content) %>

data-toc-unnumbered (+6.1.0)

具有屬性 data-toc-unnumbered="true" 的標題將被標記為未編號（不會顯示列表編號）。

警告！

要使用 data-toc-unnumbered="true"，渲染器必須具有添加 CSS 類別的選項。

請參閱以下 PR。