Development

AI Integration Advanced Basics Blocks Collections Conditionals Configuration Content Context Customizations Date Extensions Files Flow Control Functions Images Installation Loops Math Navigation PHP Regex SEO Snippets String System URL Variables

Developer Guide

Extensibility is one of the most important features of any software. Automad can be extended through two main types of packages: themes and extensions. Automad's template language makes it accessible for beginners to develop custom themes, while PHP can be used to create extensions of any complexity.

Themes are an essential part of any content management system. They define how your content is presented to your website's visitors. Automad's flexible and intuitive template language makes it easy for inexperienced developers and beginners to create themes and templates. If you're an experienced PHP developer who needs more advanced features, you can also develop templates using plain PHP.

Every theme needs a theme.json file. All subdirectories of the packages directory that contain a theme.json file side by side with at least one template are considered valid themes. Besides some basic meta data, the theme.json file controls how the fields of your theme are presented in the dashboard.

Template Language

Automad's template language provides a flexible and safe way to render content dynamically. In contrast to generic template engines, Automad's core features are integrated directly into the engine. That includes things like image processing, collections of pages and files, as well as access to an even wider range of functionality through custom functions and extensions. Due to its close relation to the core, the syntax is clean and intuitive and reduces overhead to a minimum.

Layout Settings

Aside from just stacking blocks on top of each other, the block editor provides powerful features to create flexible layouts directly in the dashboard. Blocks can be stretched to the full width of their parent container and arranged in grids using Layout Sections. While the heavy lifting is done by the render engine in the background, templates and their styles have to be prepared in order to make layouts work as expected.

Custom Block Styles

Most of the blocks only consist of plain HTML tags without classes and simply inherit the styles of a theme. However, the default styling of more complex blocks like galleries, slideshows, callouts or the mail form might not match a theme out of the box. You can use CSS custom properties to style the rendered blocks in order to match the look and feel of your theme.

Since templates are regular .php files, Automad also supports plain PHP within templates. However, variables that are only used in PHP code don't show up automatically in the dashboard and mixing PHP with the template language should be done carefully. Therefore it is not recommended to use large amounts of plain PHP in templates. Missing functionality should rather be implemented as a custom function or an extension, where the PHP code is nicely wrapped into a statement that integrates well ...

Extensions provide a convenient way of extending Automad's core functionality with custom PHP code, while still offering the clean syntax of the template language. Extensions are distributed as packages and can be used across all themes of a site. There are two types of extensions: generic extensions and custom filters.

All themes and extensions are distributed as packages. A package is simply a directory inside the packages directory of an Automad installation that contains a composer.json file. A single package can contain one or more themes, extensions, block templates and snippets at the same time. Automad uses Composer as dependency manager. Therefore releasing a package basically works the same as for any other Composer package.

Automad templates use their own syntax that is mixed with HTML and PHP. In order to make the development of themes more efficient, it is recommended to install an Automad plugin for your preferred code editor. Such plugins add syntax highlighting for the template language and, depending on the editor, snippets for autocompletion. The following editors are officially supported.

The recipes below provide a collection of ready-to-use code snippets for common tasks. They can be used as a quick reference while developing themes and extensions.

Useful Template Snippets

Find below a collection of useful snippets for common tasks using Automad's template language.