Layout Settings

Aside from just stacking blocks on top of each other, the block editor provides powerful features to create flexible layouts directly in the dashboard. Blocks can be stretched to the full width of their parent container and arranged in grids using Layout Sections. While the heavy lifting is done by the render engine in the background, templates and their styles have to be prepared in order to make layouts work as expected.

Implementing Layouts

Implementing layout support requires only two steps. First, the stylesheet of your theme should define a few CSS custom properties that configure the basic dimensions of the markup that is generated by the render engine:

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

--am-block-max-width: The maximum width of a block that is not stretched. Blocks are centered by default using automatic margins.
--am-block-margin-top: The margin on top of a block that is not the first element in its container.
--am-container-padding: The horizontal padding of the container that wraps the blocks. This value is very important, since it is used to calculate the bleeding of stretched blocks. It should reflect the actual horizontal padding of the container element in your theme.
--am-flex-gap: The default gap between blocks that are arranged side by side within a layout section.
--am-flex-min-block-width: The default minimum width of blocks within a layout section before they wrap to a new line.

The values above are the defaults. The required base styles for all blocks are added automatically to the <head> of a page by the render engine, as soon as a page contains blocks. Since these styles are added before all other stylesheets, your theme can simply override any of the properties.

Second, the best results are achieved when a block variable is wrapped in a container element that has a certain maximum width and some horizontal padding:

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

The actual class name of the container doesn't matter at all and fully depends on the CSS of your theme. Just make sure that its horizontal padding matches the value of --am-container-padding.

Aligning Other Elements

There might be additional elements on a page that have to be aligned with the centered blocks, such as a headline or a list of tags. All blocks share the am-block class that controls their width and automatic margins. You can simply add the same class to any other element that is a direct child of the container that wraps the block variable:

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

Generated Markup

Knowing the structure of the generated markup helps when fine-tuning the styles of a theme. The render engine uses the following elements and classes:

.am-block: The class of every rendered block. It defines the maximum width, the automatic margins and the top margin of a block.
am-stretched: A wrapper around stretched blocks. Stretched blocks bleed into the horizontal padding of the container and span its full width.
am-layout-section: The element that represents a layout section block. Sections that are styled as cards have the additional am-card class.
am-flex: The flexbox context inside of a layout section that arranges child blocks side by side, based on their assigned width.