Building Themes

It is recommended to disable caching during development!

Introduction

An Automad theme is actually not more than a bunch of templates, some CSS files and possible some Javascript files. To build a theme, these files have to be grouped in a sub-directory below /themes.
The name of that sub-directory also represents the name of the theme to be used in the settings.

A typical theme's directory structure will look like this:

themes/
└── my_theme/
    ├── javascript.js
    ├── styles.css
    ├── template_1.php
    └── template_2.php  

As a starting point, it is a good idea to take a look at the Standard theme shipped with Automad.


Templates

You can create templates without any PHP or programming knowledge, by just using HTML, CSS and Automad's placeholders syntax. A template is a simple .php file, containing HTML markup and Automad's placeholders to render a page dynamically. Therefore it is extremely easy to convert any static HTML page to a template, by replacing all dynamic content with the corresponding placeholder item. PHP code can be used as well within templates optionally side by side with Automad's syntax.

All templates must have the ".php" extension.


Placeholders

Like other template engines, building a website with Automad is all about using placeholders for content and dynamically created markup, like the navigation. As desribed above, using these placeholders doesn't require any knowledge of PHP. They can simply be integrated within the template's HTML markup.

The Markup

A placeholder always consists of a @ and one single character to identify its type followed by a variable or function name, wrapped in brackets:

@p(variable)                                
 ^    ^                                 
 │    └── Name                          
 └─────── Type of the placeholder (p = page variable)   

More complex tools can also have additional parameters - passed in the JSON data format.

@t(someTool{ key: value })                              
 ^    ^         ^   
 │    │         └── Options (JSON)                      
 │    └──────────── Name                            
 └───────────────── Type of the placeholder (t = toolbox)               

Automad knows 5 types of placeholders

  1. @p(var) - Page Variables
    Page variables represent the content related to a certain page.
  2. @s(var) - Shared Variables
    Shared variables are available across the whole site and hold content like the sitename.
  3. @t(tool) - Toolbox methods
    Toolbox methods provide an easy way to generate dynamic markup like navigation items or image galleries.
  4. @x(extension) - Extensions
    Extensions are basically the same as Toolbox methods, but are not part of the Automad core. They are basically optional plugins and can be added to a site without modifiyng the Automad core files.
  5. @i(template.php) - Includes
    Includes make it easy to reuse code blocks within different templates. This is actually the correct way to include a page's header and footer.

Examples

A simple template with navigation:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <!-- Generate the title tag by using the metaTitle tool -->
        @t(metaTitle)   
        <link rel="stylesheet" ... />
    </head>
    <body>
        <!-- Dynamically generate the top-level navigation -->
        <div class="navigation">@t(navTop{ homepage: true })</div>  
        <!-- The page title becomes the headline -->
        <h1>@p(title)</h1>
        <!-- Main content -->
        @p(text)
        <!-- Add a footer with a breadcrumb navigation -->
        <div class="footer">@t(navBreadcrumbs{ seperator: "/" })</div>
    </body>
</html> 

The same template, but with separated header and footer files within a sub-directory called "elements":

elements/header.php

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        @t(metaTitle)   
        <link rel="stylesheet" ... />
    </head>
    <body>
        <div class="navigation">@t(navTop{ homepage: true })</div>

elements/footer.php

        <div class="footer">@t(navBreadcrumbs{ seperator: "/" })</div>
    </body>
</html>

The actual template file

<!-- Include elements/header.php -->
@i(elements/header.php)

        <!-- The page title becomes the headline -->
        <h1>@p(title)</h1>
        <!-- Main content -->
        @p(text)

<!-- Include elements/footer.php -->        
@i(elements/footer.php)

Using plain PHP

To provide a maximum of flexibility - even though unnecessary in most cases - you can also use plain PHP within a template.

See also