ヘルパー

ヘルパーは、テンプレート内でスニペットを迅速に挿入するために使用されます。ヘルパーはソースファイル内では使用できません。

独自のカスタムヘルパーを作成することも、用意されているヘルパーを使用することも簡単にできます。

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には、文字列、配列、オブジェクト、またはオブジェクトの配列を指定できます。/<root>/の値はプレフィックスとして追加され、.css拡張子はpathに自動的に追加されます。カスタム属性にはオブジェクト型を使用します。

<%- 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">

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

js

JavaScriptファイルを読み込みます。pathには、文字列、配列、オブジェクト、またはオブジェクトの配列を指定できます。/<root>/の値はプレフィックスとして追加され、.js拡張子はpathに自動的に追加されます。カスタム属性にはオブジェクト型を使用します。

<%- 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" async></script>

<%- js([{ src: 'script.js', integrity: 'foo' }, { src: 'gallery.js', integrity: 'bar' }]) %>
// <script src="/script.js"></script>
// <script src="/gallery.js"></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 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 クラス名
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形式の文字列、Dateオブジェクト、または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

list_categories

すべてのカテゴリのリストを挿入します。

<%- list_categories([options]) %>
オプション 説明 デフォルト
orderby カテゴリの順序 name
order ソート順。1、ascは昇順、-1、descは降順。 1
show_count 各カテゴリの投稿数を表示する true
style カテゴリリストの表示スタイル。listはカテゴリを順序なしリストで表示します。無効にするにはfalseまたはその他の値を使用します。 list
separator カテゴリ間の区切り文字。（styleがlistでない場合のみ有効です） ,
depth 表示するカテゴリのレベル。0はすべてのカテゴリと子カテゴリを表示します。-1は0と似ていますが、フラットに表示されます。1は最上位カテゴリのみを表示します。 0
class カテゴリリストのクラス名。 category
transform カテゴリ名の表示を変更する関数。
suffix リンクにサフィックスを追加する。 なし

例

<%- 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はタグを順序なしリストで表示します。無効にするにはfalseまたはその他の値を使用します。 list
separator カテゴリ間の区切り文字。（styleがlistでない場合のみ有効です） ,
class タグリストのクラス名（文字列）または各タグのクラスのカスタマイズ（オブジェクト、下記参照）。 tag
transform タグ名の表示を変更する関数。list_categoriesの例を参照してください。
amount 表示するタグの数（0 = 無制限） 0
suffix リンクにサフィックスを追加する。 なし

高度なクラスのカスタマイズ

オプション 説明 デフォルト
class.ul <ul>のクラス名（styleがlistの場合のみ） tag-list（リストスタイル）
class.li <li>のクラス名（styleが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
show_count 各アーカイブの投稿数を表示する true
format 日付形式 MMMM YYYY
style アーカイブリストの表示スタイル。listはアーカイブを順序なしリストで表示します。無効にするにはfalseまたはその他の値を使用します。 list
separator アーカイブ間の区切り文字。（styleがlistでない場合のみ有効です） ,
class アーカイブリストのクラス名。 archive
transform アーカイブ名の表示を変更する関数。list_categoriesの例を参照してください。

list_posts

投稿のリストを挿入します。

<%- list_posts([options]) %>
オプション 説明 デフォルト
orderby 投稿の順序 date
order ソート順。1、ascは昇順、-1、descは降順。 1
style 投稿リストの表示スタイル。listは投稿を順序なしリストで表示します。無効にするにはfalseまたはその他の値を使用します。 list
separator 投稿間の区切り文字。（styleがlistでない場合のみ有効です） ,
class 投稿リストのクラス名。 post
amount 表示する投稿の数（0 = 無制限） 6
transform 投稿名の表示を変更する関数。list_categoriesの例を参照してください。

tagcloud

タグクラウドを挿入します。

<%- tagcloud([tags], [options]) %>
オプション 説明 デフォルト
min_font 最小フォントサイズ 10
max_font 最大フォントサイズ 20
unit フォントサイズの単位 px
amount タグの総数 unlimited
orderby タグの順序 name
order ソート順。1、ascは昇順、-1、descは降順。 1
color タグクラウドに色を付ける false
start_color 開始色。16進数（#b700ff）、rgba（rgba(183, 0, 255, 1)）、hsla（hsla(283, 100%, 50%, 1)）、またはカラーキーワードを使用できます。このオプションは、colorがtrueの場合のみ有効です。
end_color 終了色。16進数（#b700ff）、rgba（rgba(183, 0, 255, 1)）、hsla（hsla(283, 100%, 50%, 1)）、またはカラーキーワードを使用できます。このオプションは、colorがtrueの場合のみ有効です。
class タグのクラス名プレフィックス
level 異なるクラス名の数。このオプションは、classが設定されている場合のみ有効です。 10
show_count (+6.3.0) 各タグの投稿数を表示する false
count_class (+6.3.0) タグカウントのクラス名 count

例

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

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

Miscellaneous

paginator

ページネーターを挿入します。

<%- paginator(options) %>
オプション 説明 デフォルト
base 基本URL /
format URL形式 page/%d/
total ページ数 1
current 現在のページ番号 0
prev_text 前のページのリンクテキスト。prev_nextがtrueに設定されている場合のみ有効です。 Prev
next_text 次のページのリンクテキスト。prev_nextがtrueに設定されている場合のみ有効です。 Next
space スペーステキスト &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) 現在のページのクラス名 current
space_class (+6.3.0) スペースのクラス名 space
prev_class (+6.3.0) 前のページのクラス名 extend prev
next_class (+6.3.0) 次のページのクラス名 extend next
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 検索ヒントワード Search
button 検索ボタンを表示する。値はブール値または文字列にすることができます。値が文字列の場合、ボタンのテキストになります。 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タグを挿入します。

<%- 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 ページ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) 生成された目次内のアイテムの最大数 Infinity

例

<%- toc(page.content) %>

data-toc-unnumbered (+6.1.0)

属性data-toc-unnumbered="true"を持つ見出しは、番号なしとしてマークされます（リスト番号は表示されません）。

警告！

data-toc-unnumbered="true"を使用するには、レンダラーがCSSクラスを追加するオプションを持っている必要があります。

下記のPRを参照してください。