Themes

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.

Structure

An Automad theme consists of templates, a theme.json file, CSS files, and possibly JavaScript files, all grouped in a directory under packages. While not required, it's recommended to create a unique directory as your namespace and place your theme inside it, like this:

packages/
  yournamespace/
    yourtheme/
      assets/
      template.php
      page_not_found.php
      composer.json
      theme.json

Templates

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

Block Layouts

Blocks stack vertically by default, but the Block editor allows users to arrange them in grids nested within a section or stretch them to cover the full width of the parent container. The underlying flexbox wrappers are generated automatically by the render engine. However, there are a few things to keep in mind to make everything work properly. Learn more about optimizing and preparing your template markup to fully support all layout features.

404 Pages

You can also add a custom template for 404 error pages. Simply add a template named page_not_found.php to design a custom error page that matches the style of your other templates.

Block Templates

Besides page templates, themes and other packages can also provide templates for blocks. The pagelist, filelist and snippet blocks let editors choose from all block templates that are installed in the packages directory. Block templates are discovered automatically based on their location:

packages/
  yournamespace/
    yourtheme/
      blocks/
        pagelist/
          cards.php
        filelist/
          downloads.php
      snippets/
        newsletter.php

Pagelist and Filelist Templates

The configuration of a pagelist or filelist, like the type, the sort order or a glob pattern, is handled by the block editor. Therefore a block template only has to contain a foreach loop that iterates the already configured pagelist or filelist:

<# blocks/pagelist/cards.php #>
<div class="cards">
  <@ foreach in pagelist @>
    <a href="@{ url }" class="card">
      <strong>@{ title }</strong>
      <p>@{ +main | findFirstParagraph | stripTags | 100 }</p>
    </a>
  <@ end @>
</div>

<# blocks/filelist/downloads.php #>
<ul class="downloads">
  <@ foreach in filelist @>
    <li><a href="@{ :file }" download>@{ :basename }</a></li>
  <@ end @>
</ul>

Snippet Files

Snippet blocks allow editors to place template language code anywhere within the block content of a page. Instead of writing inline code, editors can also select a snippet file that is provided by a package. Snippet files are regular template files and are rendered within the context of the current page.