Block Layouts

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 blocks in a flexbox section. While the heavy lifting is done by Automad's render engine in the background, templates and their styles have to be prepared in order to make the layout work as expected.

Implementing Layouts

Implementing layout support — stretching and flexbox sections — is very straight forward and requires the following two steps:

1. The applied style sheet has to contain the following CSS cutom properties in order to configure the basic settings for the markup that is rendered by the block engine.

   :root {
       --am-block-max-width: 50rem;
       --am-block-margin-top: 2em;
       --am-container-padding: 2rem;
       --am-flex-gap: 2rem;
       --am-flex-min-block-width: 18rem;
   }
   

   The --am-block-max-width defines the maximum width of a block without being stretched. The auto-margins are applied automatically and therefore blocks are centered by default.

   The --am-block-margin-top defines the margin on top of a block that is not the first element. The --am-container-padding is very important and is needed to calculate the bleeding of stretched blocks and should just reflect the actual horizontal container padding of your theme.

   The last two properties --am-flex-gap and --am-flex-min-block-width control the default behavior of blocks within a flexbox section.

   The required CSS for the layout is added automatically to the header by the render engine as a separate file. There is no further action required. A full list of custom properties can be found here.

2. The best results can be achieved when wrapping a block variable in a container element that has a certain given maximum width and some horizontal padding.

   <div class="some-container">
       @{ +main }
   </div>
   

   The actual container class doesn't matter at all and is fully dependent on the CSS you use to style your theme.

Aligning Other Elements

The above paragraph describes how the layout of elements created by the blocks editor is handled. However, there might be additional elements on a page that have to be aligned with those centered blocks such as a headline or a tag list.

All blocks have one specific class — the .am-block class — that controls their width and auto-margins. As mentioned above the required styles are added automatically by the render engine. Therefore you can simply add the .am-block class to any other element that is a direct child of the container that contains the block variable as follows:

<div class="container">
    <h1 class="am-block">@{ title }</h1>
    @{ +main }
</div>

Examples

The following figure demonstrates what actually happens when blocks are stretched and how the behave in relation to their siblings. Note that any of the shown elements can be also part of the template markup. In other words, it is very much possible to mix generated blocks with other markup while keeping the layout tidy at the same time.

The second figure shows some nested paragraphs in a flexbox section. Note that the captions represent the generated DOM selectors.