Cheat Sheet
A quick reference for the most common Herbie features.
Page properties
---
id: "@page/about/team.html"
title: Page title
layout: default
menu_title: Menu title
redirect: /about
hidden: false
format: markdown
type: page
tags: [intro]
categories: [docs]
authors: [John Doe]
date: 2024-01-15
created: 2024-01-01
modified: 2024-06-01
cached: false
keep_extension: false
content_type: text/html
excerpt: Short teaser
twig: true
parent_id: "@page/index.md"
parent_route: ""
path: /path/to/site/pages/about/team.html
route: about/team
---
Output page properties in layout and content files:
{{ page.title }}
{{ page.layout }}
Allowed file extensions
htm, html, markdown, md, rss, rst, textile, txt, xml
Homepage
index.md
Content segments
--- default ---
--- left ---
--- right ---
Output content segments in layout files:
{{ content.default|raw }}
{{ content.left|raw }}
{{ content.right|raw }}
Event Listeners
| Name | Description |
|---|---|
| ContentRenderedEvent | Triggered after the content was rendered |
| LayoutRenderedEvent | Triggered after the layout was rendered |
| PluginsInitializedEvent | Triggered after the plugins were initialized |
| RenderLayoutEvent | Triggered when the layout is rendered |
| RenderPageEvent | Triggered when the page is rendered |
| RenderSegmentEvent | Triggered when the segment is rendered |
| ResponseEmittedEvent | Triggered after the HTTP response was emitted |
| ResponseGeneratedEvent | Triggered after the HTTP response was generated |
| TranslatorInitializedEvent | Triggered after the translator was initialized |
| TwigInitializedEvent | Triggered after Twig was initialized |
Twig Filters
| Name | Description |
|---|---|
| format_bytes | Formats a byte count in a human readable format (B, KB, MB, GB, TB, PB). Uses 1024-based units and rounds to one decimal place. Values <= 0 return "0", a single byte returns "1 Byte", and the largest unit is PB. |
| slugify | Returns a string slug for using as an URL segment. |
| spaceless | Removes whitespace between HTML tags. Herbie provides this filter because Twig deprecated the filter of the same name in 3.12. |
| twigify | Renders a string with Twig and returns the result. |
Twig Globals
| Name | Description |
|---|---|
| content | The rendered content with one or more content segments. Available only in layout files. |
| page | The page object with its properties and methods. |
| site | The site object with its properties and methods. |
Twig Functions
| Name | Description |
|---|---|
| attributes | Renders an associative array of HTML attributes into a single escaped string. |
| css_add | Adds a CSS asset to the HTML page. |
| 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" |
| css_out | Outputs the CSS assets for a given group. |
| image | Returns an image markup tag. No image processing is performed. |
| js_add | Adds a JavaScript asset to the HTML page. |
| js_out | Outputs the JavaScript assets for a given group. |
| link_download | Returns a HTML link with a file from site/media folder. |
| link_file | Returns a link to a file with additional info like file type and size. |
| link_mail | Returns a HTML mailto link. |
| link_page | Returns a HTML link with label and attributes for a given route or an URL. |
| menu_ascii_tree | Creates a text based (=ascii) tree of all pages. All parameters are optional and passed as named parameters. |
| menu_breadcrumb | Returns a breadcrumb path for the given page. All parameters are passed as an associative array. |
| menu_list | Returns a paginated list of page items with links to the first, previous, next, and last page. For the paging the GET query parameter "page" is used. |
| menu_pager | 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). |
| menu_sitemap | Creates a simple sitemap for all pages of the website based on an unordered list. All parameters are optional and passed as named parameters. |
| menu_tree | Returns an HTML menu as unordered list. All parameters are optional and passed as named parameters. |
| page_title | Returns the SEO optimized page title of the website. All parameters are optional and passed as named parameters. |
| query | Find entries with the help of the built-in fluent query builder. The query builder can be applied to any type of iterable data structure. The queried data can be narrowed down, filtered, sorted and limited. |
| snippet | Includes a snippet and outputs the rendered content of that file. Automatic escaping is disabled for all escaping strategies. |
| translate | Translates a string according to the configuration and locale settings. |
| twigify | Renders a string with Twig and returns the result. |
| url_abs | Returns the absolute URL for a given route. |
| url_rel | Returns the relative URL to a given route. |
Twig Tests
| Name | Description |
|---|---|
| path_readable | Tests if the given alias or path exists and is readable. |
| path_writable | Tests if the given alias or path exists and is writable. |
Console Commands
| Name | Description |
|---|---|
| clear-files | The clear-files command deletes asset, cache and log files from several directories. |
Plugins
| Name | Description |
|---|---|
| Contact | Contact adds a simple contact form with name, email and message fields to a website created with Herbie. |
| Dummy | This system plugin shows all possibilities how to extend Herbie. The plugin is helpful during development, but should be disabled in productive environment. |
| Imagine | This system plugin integrates Imagine, an OOP image editing library, into your Herbie website. Thanks to Imagine, you can edit images directly and apply ready-made filters and effects to them. |
| Markdown | This system plugin can be used to parse markdown-formatted texts. Internally, the plugin is responsible for parsing markdown-formatted page content. |
| Search | Search adds a simple but effective search functionality to a website created with Herbie. |
| Textile | This system plugin can be used to parse textile-formatted texts. Internally, the plugin is responsible for parsing textile-formatted page content. |
| Twig | This system plugin provides several Twig filters, functions and tests that are useful for creating a web project with Herbie. |
| reStructuredText | This system plugin can be used to parse reStructuredText-formatted texts. Internally, the plugin is responsible for parsing reStructuredText-formatted page content. |
Routing
Routes are generated from page file paths relative to site/pages/. Numeric sorting prefixes (2-doc) and the file extension are removed; index files map to the directory itself.
site/pages/2-doc/1-introduction/1-index.md -> /doc/introduction
site/pages/2-doc/3-contents/3-create-pages.md -> /doc/contents/create-pages
Special Pages
Pages such as sitemap.xml, robots.txt or atom.xml must keep their extension in the URL. Set keep_extension: true in the frontmatter.
keep_extension: true
Aliases
Aliases map shortcut names to filesystem paths:
@app -> project root
@site -> site/
@page -> site/pages/
@media -> site/media/
@web -> web/
@asset -> site/assets/
@plugin -> plugins/
@vendor -> vendor/
@snippet -> templates/snippets/
Configuration
Global defaults live in config/defaults.php; project-specific overrides go in site/config/main.php.
<?php
return [
'language' => 'en',
'theme' => 'default',
'enabledPlugins' => 'twig,markdown',
'components' => [
'urlManager' => ['niceUrls' => true],
],
];
Layouts / Themes
Layouts are Twig files in site/themes/<theme>/<layout>.twig; select one with layout: in the frontmatter.
{% extends "main.twig" %}
{% block content %}
{{ content.default|raw }}
{% endblock %}
Data Files
Files in site/data/ (YAML or JSON) are available as site.data.<name>.
site/data/menu.yml -> {{ site.data.menu }}
Middlewares
Application middlewares run for every request; route middlewares only for matching routes.
$app->addApplicationMiddleware($middleware);
$app->addRouteMiddleware('news/(.+)', $middleware);
See Middlewares for the middleware chain and examples.
Translations
Translation files live in messages/<language>.php and are used with the translate Twig function.
{{ translate('Hello') }}
Snippets
Snippets are Twig files in templates/snippets/ and can be included with snippet().
{{ snippet('@snippet/example.twig') }}
Media / Assets
Media lives in site/media/, theme assets in site/assets/. Use link_download(), image() and asset() helpers.
{{ link_download('image.jpg') }}
Page Types
Valid values for type: are page, navigation, search, rss, data and site.
type: navigation
Variables
Twig provides the current page, site data and content segments.
{{ page.title }}
{{ site.data.menu }}
{{ content.default|raw }}
{{ site.route_params.category }}
Menus / Navigation
Menus are built from page lists or data files with the menu_* functions.
{{ menu_list('main') }}
URLs & Links
Use the URL and link helpers instead of hard-coded paths.
{{ link_page('about') }}
{{ link_download('image.jpg') }}
{{ url_abs('sitemap.xml') }}
PageList / Query Builder
site.page_list filters, sorts and groups pages.
{{ site.page_list.query().where('layout=doc').order('title') }}
Caching & Debug
Use cached: false for uncached pages and HERBIE_DEBUG=1 for verbose errors. Clear caches with ./herbie clear-files.
cached: false
Plugin Configuration
Plugin options are set under plugins.<name> in site/config/main.php.
'plugins' => [
'markdown' => ['flavor' => 'gfm'],
'search' => [
// path to twig form template
'formTemplate' => '@plugin/search/templates/form.twig',
// path to twig results template
'resultsTemplate' => '@plugin/search/templates/results.twig',
// enable the internal search cache (default: true)
'useCache' => true,
],
],