Reusable Sections in Drupal Through Layout Discovery
Building modular, repeatable page sections in Drupal often feels like reinventing the wheel every time a site builder arranges blocks in Layout Builder. Layout Discovery offers a quieter, more maintainable path. By registering custom layouts through a small YAML file and a matching Twig template, teams can package a common composition — header, content, sidebar, footer — into a single, named section that editors select from a dropdown. The approach reduces duplication, accelerates governance reviews, and lets front-end and back-end developers work in parallel without one waiting on the other.
For Australian agency teams spread between Melbourne, Brisbane, Sydney, and Perth, this matters more than a stylistic preference. Multi-brand rollouts for federal and state government bodies — many of whom have standardised on Drupal — frequently demand consistent section patterns across dozens of microsites. Layout Discovery turns that requirement into a reusable module rather than a recurring rebuild.
What Layout Discovery Resolves
Layout Discovery is part of Drupal core's Layout Plugin system. Each layout is a plugin that declares its name, human-readable label, default regions, path to a template, and optional icon. Once registered, the layout becomes available wherever the Layout Builder is used: the default section storage, entity view displays, or custom block content layouts. Editors no longer need to drag blocks one by one to recreate a recurring pattern; they pick a section, and the regions are already mapped.
The benefit extends beyond convenience. Because each layout is a plugin, it inherits permissions, configuration management, and dependency handling. When a layout is removed, all references to it surface as broken configurations, which are easy to audit. That visibility is useful when working in regulated environments such as the Australian Government Web Archive Network, where accountability for content presentation forms part of audit trails.
Creating a Layout Plugin
Layouts live inside a module's layouts directory. The structure mirrors that of a plugin: one YAML file describing the layout, one Twig file rendering the markup, and an optional CSS asset. For a layout called hero_with_sidebar, the file would be my_module/layouts/hero_with_sidebar/layout-hero-with-sidebar.yml.
The YAML block contains a unique id, a label, the path to the category under which the layout appears in the UI, the template filename, a list of regions with labels, and an icon path. Categories help editors find layouts quickly; grouping sections into Content, Marketing, and Landing under the Layout Builder's section chooser keeps long dropdowns manageable. Teams working across the .au domain often localise those category labels through the interface translation system to suit both English and Australian English spelling conventions.
After adding the YAML, clearing the cache registers the plugin. The layout then appears in Layout Builder's section picker and in the layout options for any configurable field formatter or display.
Crafting the Twig Template
The Twig template sits next to the YAML file. It receives a content variable keyed by region name and a few helper attributes such as region_attributes and settings. A minimal template for a hero-with-sidebar layout might render the hero region as a full-width band and the sidebar region as an offset column beneath it, using utility classes from the active theme.
Because the layout is reusable, the markup should stay semantic and restrained. Editors will reuse the section across nodes, taxonomy landing pages, and even custom block placements. Heavy wrappers or theme-specific class names limit portability. Many Australian government projects follow the Australian Government Design System, so neutral markup that accommodates accessibility patterns like skip links and ARIA landmarks fits cleanly into the layout template without modification.
Wrapping content in a single <section> element with an aria-labelledby attribute pointing to a heading inside the hero region gives screen readers a clear navigation target, which satisfies WCAG 2.2 requirements expected by the Digital Accessibility Centre-equivalent reviews at entities such as Services Australia.
Wiring the Section into Layout Builder
Once registered, the layout is automatically exposed in every Layout Builder-enabled entity display. For some projects, that surface area is exactly the goal. In others — such as intranet portals or citizen service portals under the myGov brand — teams prefer to restrict layout choices per content type. This is achieved through Layout Builder Permissions or by overriding the layout_builder.layout plugin derivative to filter which layouts appear for a given bundle.
A practical pattern is to expose a baseline set of layouts globally and add bundle-specific sections through a small custom module. The custom module defines only the layouts relevant to that content type, keeping the editor's section list short. Site editors in Sydney-based publishing houses have reported measurable time savings when their section pickers drop from two dozen entries to half a dozen.
Configuration management becomes more pleasant as well. Because each layout is registered by module, adding a new layout to a site is as simple as enabling the module in a deployment pipeline. Rolling it out across an Acquia or Pantheon environment — both popular with Australian enterprises — becomes a single git commit reviewed in the standard workflow.
Version Control and Team Workflow
Treating layouts like any other code asset changes how multi-disciplinary teams collaborate. Designers iterate on Twig templates and CSS, developers manage the YAML, and content editors consume the finished sections without needing to understand the underlying configuration. A pull request titled "Add a three-up resource card layout for landing pages" reads clearly to a project manager in Melbourne as to a senior developer in Adelaide.
This separation pays off during handover. When an agency in Surry Hills transitions a site to an in-house team at a government department, the receiving staff can review the available layouts through the Layout Builder UI, examine the Twig templates in the theme, and trace everything back to specific modules in the codebase. Auditors working toward ISO 27001 alignment — a standard many Australian .au sites now pursue — appreciate that level of provenance.
Teams working in Australian English contexts can also lock in a spelling pass at the layout label level. Labels are translatable strings, so a project that uses "organisation" rather than "organization" can hold its convention across every section label without post-launch find-and-replace scripts.
Choosing Between Layout Discovery and Manual Block Layouts
The choice between a custom Layout Discovery plugin and a one-off Layout Builder configuration depends on how often the section recurs, who else needs to use it, and how the section will evolve. The table below maps common scenarios to a recommended approach.
| Scenario | Recommended Approach | Reason |
|---|---|---|
| A promotional banner used on every campaign page | Layout Discovery plugin | Consistent markup, single source of truth |
| A one-off hero on a marketing landing page | Manual Layout Builder section | Faster to configure, low reuse value |
| A resource card stack shared between editorial and event content types | Layout Discovery plugin with theme suggestions | Centralises design tokens and content structure |
| A landing page that changes shape every quarter | Manual Layout Builder section | Allows editors to experiment without redeployment |
| A government service summary block used across 12 agency sites | Layout Discovery plugin packaged as a contrib module | Simplifies multi-site configuration management |
| A blog post sidebar with bespoke widgets | Layout Discovery plugin scoped to a single feature module | Keeps related blocks and the section together |
| A quick layout concept test during design sprints | Manual Layout Builder section | Avoids module boilerplate during exploration |
In short, reach for Layout Discovery when reuse is intended, when the section carries governance weight, or when downstream teams need to drop the layout into new content without intervention. Reach for manual sections when the layout is exploratory, low-traffic, or tightly bound to a single piece of content.
Maintaining a small library of well-named layouts accelerates future builds. Editors stop asking "how do I make a three-column section again?" and start requesting new arrangements from developers by name. That shift in vocabulary marks the moment a Drupal site has moved from ad-hoc composition to a deliberate design system running on the Layout Discovery foundations provided by core.