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,
    ],
],