Customizing Blocks

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 properties to style the rendered blocks to match your theme. Some block types — pagelist and filelist blocks — also support custom templates to be used for rendering content.

Take a look a the custom block templates shipped with the Standard theme to get started quickly.

Styling Blocks

To customize the look of rendered blocks, Automad provides a couple of custom properties which can be overriden in .css, .less or .sass files of a theme. You can find a collection of all available custom properties in the variables.less file which is shipped with Automad.

automad/blocks/less/variables.less

To change for example the styling of the buttons block, you can define the following custom properties in your stylesheets:

:root {
    --am-button-margin: 0.5rem;
    --am-button-padding-vertical: 0.5rem;
    --am-button-padding-horizontal: 1rem;
    --am-button-font-size: inherit;
    --am-button-lineheight: 1.6;
    ...
}

Custom Templates

The pagelist and the filelist blocks support the use of custom templates. Conceptionally those templates are just normal snippet files containing a foreach loop — either iterating a pagelist or a filelist object.

Pagelist Block Templates

Creating a custom pagelist block template is pretty straight forward. To be available in the block editor, a .php file including a foreach loop has to be placed within a blocks/pagelist directory somewhere in a package. So its path basically has to match /packages/**/blocks/pagelist/*.php like for example the custom templates of the Standard themes shipped with Automad:

/packages/standard/templates/blocks/pagelist/simple.php

The actual pagelist configuration is handled by the block editor user interface and therefore the content of such a template file is not more than just a foreach loop snippet:

<?php defined('AUTOMAD') or die('Direct access not permitted!'); ?>
<section>
    <@ foreach in pagelist @>
        <p>
            <a href="@{ url }"><b>@{ title }</b></a>
            <br>
            @{ tags }
        </p>
    <@ end @>
</section>

Filelist Block Templates

Custom block templates for filelists work exactly the same as for pagelist blocks. They only differ in their location and in the type of object to be iterated. Their path has to match /packages/**/blocks/filelist/*.php like:

/packages/vendor/name/blocks/filelist/simple.php

Also here the configuration of the filelist is handled by the block editor user interface. Again, the content of the template is just a foreach loop iterating a filelist object.

<?php defined('AUTOMAD') or die('Direct access not permitted!'); ?>
<section>
    <ul>
        <@ foreach in filelist @>
            <li>
                <a href="@{ :file }">@{ :basename }</a>
            </li>
        <@ end @>
    </ul>
</section>