Twig Functions

Herbie is using Twig Functions for generating content in layout and content files. In addition to the built-in functions of Twig itself, the following functions are available.

abs_url

Returns the absolute URL for a given route.

Parameter Type Description Default
route string The route to a page.
[return] string The absolute URL.
Example:
{{ abs_url("doc/contents/variables") }}

add_css

Adds a CSS asset to the HTML page.

Parameter Type Description Default
paths string|array One or more paths to CSS resources.
attr array Attribute for the HTML tag. []
group string A name to group the CSS. null
raw bool Returns CSS inline instead of as a link. false
pos int The sort order of the CSS asset. -1
[return] void
Example:
{{ add_css("@site/themes/styles.css", {class: "styles"}, "default", false, 1) }}

add_js

Adds a JavaScript asset to the HTML page.

Parameter Type Description Default
paths string|array One or more paths to JavaScript resources.
attr array Attribute for the HTML tag. []
group string A name to group the JavaScript. null
raw bool Returns JavaScript inline instead of as a link. false
pos int The sort order of the JavaScript asset. -1
[return] void
Example:
{{ add_js("@site/themes/script.js", {class: "scripts"}, "default", false, 1) }}

css_classes

Returns a string with CSS classes, to be used within an HTML attribute, for example the html or body tag. This allows to address any page, theme, layout or language via CSS selector. Such a string looks like: "page-blog theme-default layout-blog language-en"

Parameter Type Description Default
[return] string The string with CSS classes.
Example:
{{ css_classes() }}

file

Returns a link to a file with additional info like file type and size.

Parameter Type Description Default
path string The relative web path to the file.
label string The label for the HTML tag. "
info bool If true file info will be added after the link. false
attribs array One or more HTML attributes. [ ]
[return]
Example:
{{ file("media/download.pdf", "Download", true, {class:"download"}) }}

image

Returns an image markup tag. No image processing is performed.

Parameter Type Description Default
src string The relative web path to the image file.
width int The width of the image. 0
height int The height of the image. 0
alt string The alt text of the image. ""
class string The HTML class attribute. ""
[return] string The image markup
Example:
{{ image("media/portrait.jpg", 100, 200, "Portrait", "photo") }}

Creates a text based (=ascii) tree of all pages. All parameters are optional and passed as named parameters.

Parameter Type Description Default
route string The tree from the given route. ""
maxDepth int The maximum depth level of the tree (-1 = unlimited). -1
showHidden bool Show hidden pages. false
[return] string The tree rendered as ascii text
Example:
{{ menu_ascii_tree("doc", 2, true) }}

Returns a breadcrumb path for the given page. All parameters are passed as an associative array.

Parameter Type Description Default
delim string The delim. ""
homeLink array|string The link to the homepage. An array must be like [route, label]. ""
reverse bool Reverse the breadcrumb. false
[return] string The breadcrumb path as HTML.
Example:
{{ menu_breadcrumb(" / ", ["", "Homepage"], true) }}

Returns a paginated list of page items with links to the previous and next page. For the paging the GET parameter "page" is used.

Parameter Type Description Default
pageList PageList The page list. null
filter string One or more filters. ""
sort string The sort field. ""
shuffle bool If set the list is shuffled. false
limit int The limit 10
template string The path to the twig template. @snippet/listing.twig
[return] string The rendered markup
Example:
{{ menu_list(site.pageList, "parentRoute|doc", "title|asc", false, 3, "@snippet/listing.twig") }}

Creates a pagination with links to the previous an next page within the current page branch. All parameters are optional and passed as named parameters (see twig).

Parameter Type Description Default
limit string Limits the pagination to a certain branch of the page tree.
prevPageLabel string The label for the "previous" link. If empty the page title will be shown.
nextPageLabel string The label for the "next" link. If empty the page title will be shown.
prevPageIcon string The icon for the "previous" link.
nextPageIcon string The icon for the "next" link.
linkClass string The CSS class name for the element. Various other class names are assembled from this class name.
template string The template. <div class="{class}">{prev}{next}</div>
[return] string The generated markup
Example:
{{ pager("doc/contents/", "Previous", "Next", "&lt;", "&gt;", "nav-pager", "<div class=\"{class}\">{prev}{next}</div>") }}

Creates a simple sitemap for all pages of the website based on an unordered list. All parameters are optional and passed as named parameters.

Parameter Type Description Default
route string Limits the sitemap to a certain branch of the page tree. ""
maxDepth int The maximum depth level of the sitemap. -1
showHidden bool Show hidden pages. false
class string The CSS class name. sitemap
[return] string The generated markup
Example:
{{ menu_sitemap("doc", 1, false, "nav-sitemap") }}

Returns an HTML menu as unordered list. All parameters are optional and passed as named parameters.

Parameter Type Description Default
route string The menu from the given route. ""
maxDepth int The maximum depth level of the tree. -1
showHidden bool Show hidden pages. false
class string The CSS class for the menu. menu
[return] string The menu as unordered list
Example:
{{ menu_tree("doc", 1, false, "nav-menu") }}

output_css

Outputs the CSS assets for a given group.

Parameter Type Description Default
group string The grouped CSS. null
addTimestamp bool If true, a GET param with the modification timestamp of the file is added.
[return] void The CSS assets
Example:
{{ output_css("default") }}

output_js

Outputs the JavaScript assets for a given group.

Parameter Type Description Default
group string The grouped JavaScript. null
addTimestamp bool If true, a GET param with the modification timestamp of the file is added.
[return] string The JavaScript assets
Example:
{{ output_js("default") }}

Returns a HTML link with label and attributes for a given route or an URL.

Parameter Type Description Default
route string The route or the URL to a page.
label string The label.
attribs array The HTML attributes passed as an associative array.
[return] string The link to a route
Example:
{{ page_link("doc/contents/variables", "Content variables", {class: "page-link"}) }}

page_title

Returns the SEO optimized page title of the website. All parameters are optional and passed as named parameters.

Parameter Type Description Default
delim string The delim. " / "
siteTitle string The title of the website. If set this title is appended on every page. null
rootTitle string The title of the root page of the website. If set this title is displayed on root page only. null
reverse bool Reverse the page title path. false
[return] string The page title of the website
Example:
{{ page_title(" / ", "My Blog", "Welcome to My Blog", true) }}

snippet

Includes a snippet and outputs the rendered content of that file. Automatic escaping is disabled for all escaping strategies.

Parameter Type Description Default
path string The path to the snippet.
context array The context variables to pass to the snippet. []
[return] string The included snippet
Example:
{{ snippet("@site/custom-snippet.twig", {foo: "bar"}) }}

translate

Translates a string according to the configuration and locale settings.

Parameter Type Description Default
category string The translate category
message string The message to translate
params array Params injected into translate function [ ]
[return] string The translated message
Example:
{{ translate("app", "Plugin \"{plugin}\" enabled but not found!", {plugin: "dummy"}) }}

url

Returns the relative URL to a given route.

Parameter Type Description Default
route string The route to a page.
[return] string The relative URL.
Example:
{{ url("doc/contents") }}