• ♡ Sponsor

    Building Themes

    #Development #Package #Theme

    Themes are an essential part of a content management system. They define the way your content is presented to the visitors of your website. Automad's flexible and intuitive template language enables also inexperienced developers or beginners to create themes and templates on their own. In case you are an experienced PHP developer and you need more unusual features, you can also develop templates using plain PHP.

    Check out the Theme Skeleton theme and the Cheat Sheets to get started!

    Structure

    An Automad theme is actually not more than a bunch of templates, a theme.json file, some CSS files and possibly some Javascript files, grouped within a directory under packages. While it is not required, it is recommended to create a unique directory as your namespace and place your theme in there as shown here:

    packages/
      yournamespace/
        yourtheme/
          css/
          js/
          template.php
          page_not_found.php
          theme.json
    

    Note that all custom modifications to the Standard package are lost when updating Automad. Please copy themes to your own namespace (subdirectory), in case you want to keep any custom modifications on updates.

    Templates

    A template file is a simple .php file containing HTML markup mixed with some template language code to render your content dynamically. While PHP is actually not required within the template file, the .php extension must be used to identify a template.

    Before you start to develop your own themes, take a look at the plugins page to install Automad syntax highlighting and snippets for your favorite IDE or editor.

    Block Layouts

    While blocks stack vertically by default, the Block editor allows users to also arrange them in grids nested in a section or even stretch them to cover the full width of the parent container. The underlaying flexbox wrappers are generated automatically by the render engine. However there are some things to be taken care of in order to make things work. You can read more here about optimizing and preparing your template markup to fully support all layout features.

    Learn More

    Block Templates

    Blocks with dynamic content — pagelist and filelist — can use custom templates to control the content and the style of the rendered output. Follow this guide to develop your own custom blocks.

    404

    There is also the option to add a custom template for a 404 page. Simply add a template with the name page_not_found.php to design a custom error page matching the other templates of your theme.


    More in Building Themes

    • theme.json
    • Template Language
    • Block Layouts
    • Customizing Blocks
    • Plain PHP

    Related

    System  ⁄
    Debugging — System

    During development of extensions it can be handy to see what Automad is doing. Therefore it is possible to send logging information to your browser's console. You can log any item, object or just a text notice using the following method in your extension or theme.

    System  ⁄
    Installing Packages — System

    Automad can be easily extended by installing custom packages. A package can be a theme or a PHP extension or a combination of both. The easiest way to install packages is to use the Packages section on the Automad dashboard. It also helps you to get an overview about available ...

    Developer Guide

    Extensibility is one of the most important features of any software. Basically there are two types of packages to extend the functionality of Automad: themes and extensions. While Automad's template language allows beginners to develop their own themes, it is also possible to use ...

    Building Themes  ⁄
    theme.json — Building Themes

    Every theme needs a theme.json to work. As mentioned before, all subdirectories of the packages directory containing a theme.json side by side with at least one template are to be considered as valid themes. Please see the list below for all required fields.

    Building Themes  ⁄
    Template Language — Building Themes

    Automad's template language provides a flexible and safe way to render content dynamically. In contrast to other generic template engines, the Automad core functions are integrated into the engine. That includes such things as image processing as well as a the access to an even ...

    Building Themes  ⁄
    Block Layouts — Building Themes

    Aside from just stacking blocks on top of each other, Automad's block editor provides some handy features to create flexible layout directly in the block editor. It is possible to stretch a block to the full with of the parent container to make it stand out as well as to arrange ...

    Building Themes  ⁄
    Customizing Blocks — Building Themes

    Most of the blocks only consist of pure HTML tags without classes and just inherit theme styles when being displayed. However the default styling of more complex blocks like the mail form or the gallery block might not be matching a theme out of the box. You can use CSS custom ...

    Building Themes  ⁄
    Plain PHP — Building Themes

    Automad supports plain PHP in template files. However, variables used in plain PHP blocks will not show up automatically in the dashboard and mixing PHP with Automad's template engine should be done carefully. Therefore it is not recommended to use plain PHP in normal templates. ...

    Developer Guide  ⁄
    Developing Extensions — Developer Guide

    The extension interface provides a convenient way of extending Automad's core functionality with custom PHP code while still offering Automad's template syntax. There are basically two types of template language extensions: generic extensions and custom pipe functions. Check out ...

    Developing Extensions  ⁄
    Generic Extensions — Developing Extensions

    In case you are missing any advanced feature while developing themes using Automad's template language, you are able to implement that functionality as a generic extension written in plain PHP.

    Developing Extensions  ⁄
    Custom Pipe Functions — Developing Extensions

    Automad provides already some basic string manipulation functions to be used with the pipe operator. However, in some cases it my be necessary to use a custom function to modify the content of a variable. Custom pipe functions can be written in plain PHP. Thier basic setup is ...

    Developer Guide  ⁄
    Publishing Packages — Developer Guide

    Automad uses Composer as dependency manager. Therefore packages can be made public by submitting them as Composer packages to the Packagist website. Published Automad packages also automatically appear in the package browser. The process of releasing a package is basically the ...

    Developer Guide  ⁄
    Editor Plugins — Developer Guide

    To make the development of themes more efficient, it is recommended to install one of the Automad plugins for the editors listed below. Those plugins will add syntax highlighting for the Automad template engine as well as the most common snippets for autocompletion.

    Developer Guide  ⁄
    Cheat Sheets — Developer Guide

    In case you prefer to start developing a theme or extension without reading the full documention, the cheat sheets below are a good point to start. In addition to this page there is also the theme skeleton package available to help you getting started.

    Cheat Sheets  ⁄
    Useful Template Snippets — Cheat Sheets

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

    Cheat Sheets  ⁄
    Plain PHP Snippets — Cheat Sheets

    In case you want to develop a new extension or use PHP in your templates, the collection of common code snippets below might help you getting started quickly.

    Cheat Sheets  ⁄
    Creating Theme Packages — Cheat Sheets

    This guide describes step by step the workflow of setting up and publish a new theme. It assumes you're familiar with Visual Code Studio and working on a system with a Bash shell or similar — like macOS or Linux.

    Headless Mode

    Activating the headless mode turns Automad into a back-end only content management system without a presentation layer that focuses entirely on content creation. While the Dashboard can still be used to manage content, all data and files are made accessible via a read-only JSON ...

    Packages

    Browse free Composer packages and install themes and extensions for your Automad site.

    • Automad
    • Developer Guide
    • Building Themes
    Discuss
    Packages
    Release Notes
    Support
    Terms of Use
      Become a Sponsor
      GitHub
      Twitter
      Facebook
      Instagram
      2013-2022 by Marc Anton Dahmen
    Released under the MIT license

    A faceless machine, creating one's portrait in the internet.
  • Automad
  • Getting Started
  • System
  • User Guide
  • Developer Guide
  • Headless Mode
  • Discuss
  • Packages
  • Developer Guide ←
  • Building Themes
  • theme.json
  • Template Language →
  • Block Layouts
  • Customizing Blocks
  • Plain PHP