ヘルパーを使うことで、テンプレートにスニペットを素早く挿入できます。ソースファイル内では使用できません。
独自のカスタムヘルパーを簡単に作成するほか、既に用意されているヘルパーを使うこともできます。
URL
url_for
ルートパスが先頭に付与されたURLを返します。出力は自動的にエンコードされます。
<%- url_for(path, [option]) %>
|
| オプション |
説明 |
デフォルト |
relative |
相対リンクを出力 |
config.relative_linkの値 |
例:
<%- url_for('/a/path') %>
|
相対リンクはデフォルトでrelative_linkオプションに従います。
例えば、記事やページのパスが ‘/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への相対URLを返します。
<%- relative_url(from, to) %>
|
例:
<%- relative_url('foo/bar/', 'css/style.css') %>
|
full_url_for
config.urlを先頭に付与したURLを返します。出力は自動的にエンコードされます。
<%- full_url_for(path) %>
|
例:
_config.yml
url: https://example.com/blog
|
<%- full_url_for('/a/path') %>
|
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'}) %>
|
HTMLタグ
css
CSSファイルを読み込みます。 path には文字列、配列、オブジェクト、またはオブジェクトの配列を指定できます。/<root>/の値が先頭に付与され、.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 には文字列、配列、オブジェクト、またはオブジェクトの配列を指定できます。/<root>/の値が先頭に付与され、.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 |
クラス名 |
|
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 |
クラス名 |
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 |
クラス名 |
id |
ID |
width |
画像の幅 |
height |
画像の高さ |
favicon_tag
ファビコンを挿入します。
feed_tag
フィードリンクを挿入します。
<%- feed_tag(path, [options]) %>
|
| オプション |
説明 |
デフォルト |
title |
フィードのタイトル |
config.title |
type |
フィードのタイプ |
|
例:
<%- feed_tag('atom.xml') %>
<%- feed_tag('rss.xml', { title: 'RSS Feed', type: 'rss' }) %>
<%- feed_tag() %>
|
条件付きタグ
is_current
pathが現在のページのURLと一致するかチェックします。厳密な比較を行う場合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
文字列をタイトルケースに変換します。
例:
<%- 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以内に切り捨てます。デフォルトは30文字です。
<%- truncate(text, [options]) %>
|
例:
<%- 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 |
コンテンツをキャッシュします（フラグメントキャッシュを使用） |
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
timeタグを挿入します。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 は順序なしリストでカテゴリを表示。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> のクラス名（list スタイルのみ） |
tag-list (list スタイル) |
class.li |
<li> のクラス名（list スタイルのみ） |
tag-list-item (list スタイル) |
class.a |
<a> のクラス名 |
tag-list-link (list スタイル) tag-link (通常スタイル) |
class.label |
タグラベルを格納する <span> のクラス名（通常スタイルでclass.label が設定されている場合のみ、ラベルは <span> に入れられます） |
tag-label (通常スタイル) |
class.count |
タグカウンタが格納される <span> のクラス名（show_count が true の場合のみ） |
tag-list-count (list スタイル) 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 |
タグの総数 |
無制限 |
orderby |
タグの順序 |
name |
order |
並び順。1,asc で昇順；-1,desc で降順 |
1 |
color |
タグクラウドを色付けするか？ |
false |
start_color |
開始色。hex (#b700ff), rgba (rgba(183, 0, 255, 1)), hsla (hsla(283, 100%, 50%, 1)) または 色キーワード を指定可能。このオプションは color が true の場合のみ機能します。 |
|
end_color |
終了色。hex (#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 |
例:
<%- tagcloud() %>
<%- tagcloud({amount: 30}) %>
|
その他の機能
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 |
スペーステキスト |
… |
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: '>'
}) %>
|
<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 |
フォームのクラス名 |
search-form |
text |
検索ヒントワード |
Search |
button |
検索ボタンを表示。booleanまたはstringを指定できます。stringの場合はボタンのテキストになります。 |
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 タグを挿入します。
例:
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 |
例:
data-toc-unnumbered (6.1.0以上)
属性 data-toc-unnumbered="true" を持つ見出しは番号無しとしてマークされます（リスト番号が表示されません）。
Warning!data-toc-unnumbered="true" を使用するには、CSSクラスを追加できるレンダラーを使う必要があります。
以下のPRを参照してください。