Loading...

Loading...

Helpers are used in templates to help you insert snippets quickly. Helpers cannot be used in source files.

You could easily write your own custom helper or use our ready-made helpers.

URL

url_for

Returns a URL with the root path prefixed. Output is encoded automatically.

<%- url_for(path, [option]) %>
OptionDescriptionDefault
relativeOutput relative linkValue of config.relative_link

Examples:

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

Relative link, follows relative_link option by default
e.g. post/page path is ‘/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

Returns the relative URL from from to to.

<%- relative_url(from, to) %>

Examples:

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

full_url_for

Returns a URL with the config.url prefixed. Output is encoded automatically.

<%- full_url_for(path) %>

Examples:

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

gravatar

Returns the gravatar image URL from an email.

If you don’t specify the [options] parameter, the default options will apply. Otherwise, you can set it to a number which will then be passed on as the size parameter to Gravatar. Finally, if you set it to an object, it will be converted into a query string of parameters for Gravatar.

<%- gravatar(email, [options]) %>
OptionDescriptionDefault
sOutput image size80
dDefault image
fForce default
rRating

More info: Gravatar

Examples:

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

css

Loads CSS files. path can be a string, an array, an object or an array of objects. /<root>/ value is prepended while .css extension is appended to the path automatically. Use object type for custom attributes.

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

Examples:

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

Loads JavaScript files. path can be a string, an array, an object or an array of objects. /<root>/ value is prepended while .js extension is appended to the path automatically. Use object type for custom attributes.

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

Examples:

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

Inserts a link.

<%- link_to(path, [text], [options]) %>
OptionDescriptionDefault
externalOpens the link in a new tabfalse
classClass name
idID

Examples:

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

Inserts a mail link.

<%- mail_to(path, [text], [options]) %>
OptionDescription
classClass name
idID
subjectMail subject
ccCC
bccBCC
bodyMail content

Examples:

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

Inserts an image.

<%- image_tag(path, [options]) %>
OptionDescription
altAlternative text of the image
classClass name
idID
widthImage width
heightImage height

favicon_tag

Inserts a favicon.

<%- favicon_tag(path) %>

feed_tag

Inserts a feed link.

<%- feed_tag(path, [options]) %>
OptionDescriptionDefault
titleFeed titleconfig.title
typeFeed type

Examples:

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

Conditional Tags

is_current

Check whether path matches the URL of the current page. Use strict options to enable strict matching.

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

is_home

Check whether the current page is home page.

<%- is_home() %>

is_home_first_page (+6.3.0)

Check whether the current page is the first of home page.

<%- is_home_first_page() %>

is_post

Check whether the current page is a post.

<%- is_post() %>

is_page

Check whether the current page is a page.

<%- is_page() %>

is_archive

Check whether the current page is an archive page.

<%- is_archive() %>

is_year

Check whether the current page is a yearly archive page.

<%- is_year() %>

is_month

Check whether the current page is a monthly archive page.

<%- is_month() %>

is_category

Check whether the current page is a category page.
If a string is given as parameter, check whether the current page match the given category.

<%- is_category() %>
<%- is_category('hobby') %>

is_tag

Check whether the current page is a tag page.
If a string is given as parameter, check whether the current page match the given tag.

<%- is_tag() %>
<%- is_tag('hobby') %>

String Manipulation

trim

Removes prefixing and trailing spaces of a string.

<%- trim(string) %>

strip_html

Sanitizes all HTML tags in a string.

<%- strip_html(string) %>

Examples:

<%- strip_html('It\'s not <b>important</b> anymore!') %>
// It's not important anymore!

titlecase

Transforms a string into proper title caps.

<%- titlecase(string) %>

Examples:

<%- titlecase('this is an apple') %>
# This is an Apple

markdown

Renders a string with Markdown.

<%- markdown(str) %>

Examples:

<%- markdown('make me **strong**') %>
// make me <strong>strong</strong>

render

Renders a string.

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

Examples:

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

See Rendering for more details.

word_wrap

Wraps text into lines no longer than length. length is 80 by default.

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

Examples:

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

truncate

Truncates text after certain length. Default is 30 characters.

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

Examples:

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

Escapes HTML entities in a string.

<%- escape_html(str) %>

Examples:

<%- escape_html('<p>Hello "world".</p>') %>
// <p>Hello "world".</p>

Templates

partial

Loads other template files. You can define local variables in locals.

<%- partial(layout, [locals], [options]) %>
OptionDescriptionDefault
cacheCache contents (Use fragment cache)false
onlyStrict local variables. Only use variables set in locals in templates.false

fragment_cache

Caches the contents in a fragment. It saves the contents within a fragment and serves the cache when the next request comes in.

<%- fragment_cache(id, fn);

Examples:

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

Date & Time

date

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

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

Examples:

<%- date(Date.now()) %>
// 2013-01-01

<%- date(Date.now(), 'YYYY/M/D') %>
// Jan 1 2013

date_xml

Inserts date in XML format. date can be unix time, ISO string, date object, or Moment.js object.

<%- date_xml(date) %>

Examples:

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

time

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

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

Examples:

<%- time(Date.now()) %>
// 13:05:12

<%- time(Date.now(), 'h:mm:ss a') %>
// 1:05:12 pm

full_date

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

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

Examples:

<%- 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 library.

List

list_categories

Inserts a list of all categories.

<%- list_categories([options]) %>
OptionDescriptionDefault
orderbyOrder of categoriesname
orderSort of order. 1, asc for ascending; -1, desc for descending1
show_countDisplay the number of posts for each categorytrue
styleStyle to display the category list. list displays categories in an unordered list. Use false or any other value to disable it.list
separatorSeparator between categories. (Only works if style is not list),
depthLevels of categories to be displayed. 0 displays all categories and child categories; -1 is similar to 0 but displayed in flat; 1 displays only top level categories.0
classClass name of category list.category
transformThe function that changes the display of category name.
suffixAdd a suffix to link.None

Examples:

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

Inserts a list of all tags.

<%- list_tags([options]) %>
OptionDescriptionDefault
orderbyOrder of tagsname
orderSort of order. 1, asc for ascending; -1, desc for descending1
show_countDisplay the number of posts for each tagtrue
styleStyle to display the tag list. list displays tags in an unordered list. Use false or any other value to disable it.list
separatorSeparator between categories. (Only works if style is not list),
classClass name of tag list (string) or customize each tag’s class (object, see below).tag
transformThe function that changes the display of tag name. See examples in list_categories.
amountThe number of tags to display (0 = unlimited)0
suffixAdd a suffix to link.None

Class advanced customization:

OptionDescriptionDefault
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 nametag-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

Inserts a list of archives.

<%- list_archives([options]) %>
OptionDescriptionDefault
typeType. This value can be yearly or monthly.monthly
orderSort of order. 1, asc for ascending; -1, desc for descending1
show_countDisplay the number of posts for each archivetrue
formatDate formatMMMM YYYY
styleStyle to display the archive list. list displays archives in an unordered list. Use false or any other value to disable it.list
separatorSeparator between archives. (Only works if style is not list),
classClass name of archive list.archive
transformThe function that changes the display of archive name. See examples in list_categories.

list_posts

Inserts a list of posts.

<%- list_posts([options]) %>
OptionDescriptionDefault
orderbyOrder of postsdate
orderSort of order. 1, asc for ascending; -1, desc for descending1
styleStyle to display the post list. list displays posts in an unordered list. Use false or any other value to disable it.list
separatorSeparator between posts. (Only works if style is not list),
classClass name of post list.post
amountThe number of posts to display (0 = unlimited)6
transformThe function that changes the display of post name. See examples in list_categories.

tagcloud

Inserts a tag cloud.

<%- tagcloud([tags], [options]) %>
OptionDescriptionDefault
min_fontMinimum font size10
max_fontMaximum font size20
unitUnit of font sizepx
amountTotal amount of tagsunlimited
orderbyOrder of tagsname
orderSort order. 1, asc as ascending; -1, desc as descending1
colorColorizes the tag cloudfalse
start_colorStart color. You can use hex (#b700ff), rgba (rgba(183, 0, 255, 1)), hsla (hsla(283, 100%, 50%, 1)) or color keywords. This option only works when color is true.
end_colorEnd color. You can use hex (#b700ff), rgba (rgba(183, 0, 255, 1)), hsla (hsla(283, 100%, 50%, 1)) or color keywords. This option only works when color is true.
classClass name prefix of tags
levelThe number of different class names. This option only works when class is set.10
show_count (+6.3.0)Display the number of posts for each tagfalse
count_class (+6.3.0)Class name of tag countcount

Examples:

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

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

Miscellaneous

paginator

Inserts a paginator.

<%- paginator(options) %>
OptionDescriptionDefault
baseBase URL/
formatURL formatpage/%d/
totalThe number of pages1
currentCurrent page number0
prev_textThe link text of previous page. Works only if prev_next is set to true.Prev
next_textThe link text of next page. Works only if prev_next is set to true.Next
spaceThe space text&hellp;
prev_nextDisplay previous and next linkstrue
end_sizeThe number of pages displayed on the start and the end side1
mid_sizeThe number of pages displayed between current page, but not including current page2
show_allDisplay all pages. If this is set to true, end_size and mid_size will not workfalse
escapeEscape HTML tagstrue
page_class (+6.3.0)Page class namepage-number
current_class (+6.3.0)Current page class namecurrent
space_class (+6.3.0)Space class namespace
prev_class (+6.3.0)Previous page class nameextend prev
next_class (+6.3.0)Next page class nameextend next
force_prev_next (+6.3.0)Force display previous and next linksfalse

Examples:

<%- paginator({
  prev_text: '<',
  next_text: '>'
}) %>
<!-- Rendered as -->
<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
}) %>
<!-- 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

Inserts a Google search form.

<%- search_form(options) %>
OptionDescriptionDefault
classThe class name of formsearch-form
textSearch hint wordSearch
buttonDisplay search button. The value can be a boolean or a string. If the value is a string, it’ll be the text of the button.false

number_format

Formats a number.

<%- number_format(number, [options]) %>
OptionDescriptionDefault
precisionThe precision of number. The value can be false or a nonnegative integer.false
delimiterThe thousands delimiter,
separatorThe separator between the fractional and integer digits..

Examples:

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

Inserts Open Graph data.

<%- open_graph([options]) %>
OptionDescriptionDefault
titlePage title (og:title)page.title
typePage type (og:type)article(post page)
website(non-post page)
urlPage URL (og:url)url
imagePage images (og:image)All images in the content
authorArticle author (og:article:author)config.author
dateArticle published time (og:article:published_time)Page published time
updatedArticle modified time (og:article:modified_time)Page modified time
languageArticle language (og:locale)page.lang \|\| page.language \|\| config.language
site_nameSite name (og:site_name)config.title
descriptionPage description (og:description)Page excerpt or first 200 characters of the content
twitter_cardTwitter card type (twitter:card)summary
twitter_idTwitter ID (twitter:creator)
twitter_siteTwitter Site (twitter:site)
twitter_imageTwitter Image (twitter:image)
google_plusGoogle+ profile link
fb_adminsFacebook admin ID
fb_app_idFacebook App ID

toc

Parses all heading tags (h1~h6) in the content and inserts a table of contents.

<%- toc(str, [options]) %>
OptionDescriptionDefault
classClass nametoc
class_item (+6.3.0)Class name of item${class}-item
class_link (+6.3.0)Class name of link${class}-link
class_text (+6.3.0)Class name of text${class}-text
class_child (+6.3.0)Class name of child${class}-child
class_number (+6.3.0)Class name of number${class}-number
class_level (+6.3.0)Class name prefix of level${class}-level
list_numberDisplays list numbertrue
max_depthMaximum heading depth of generated toc6
min_depthMinimum heading depth of generated toc1
max_items (+7.3.0)Maximum number of items in generated tocInfinity

Examples:

<%- 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 displayed).

warn Warning!

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

Please see the below PRs.

Comments
Data Loading...