Drupal 11 theming controls site appearance through Twig templates, Layout Builder sections, and custom blocks. A theme is the set of templates, styles, scripts, and settings that shape pages, content areas, and reusable parts. Use Twig for consistent markup, Layout Builder for page-level arrangement, and custom blocks for repeated content units like calls to action, testimonials, or location cards. This split keeps design control with developers while giving editors safe layout choices.
Table of Contents
- How does Twig shape pages?
- What belongs in a Drupal 11 theme?
- When should you use Layout Builder?
- How do you build a custom block for theming?
- How do you keep a theme fast and maintainable?
How does Twig shape pages?
Twig is the template language that turns Drupal data into HTML. It keeps display logic separate from business logic, so templates focus on markup and simple conditions. Variables arrive from preprocess functions, then the template prints fields, links, and text. Template suggestions let one template serve many pages or one exact case.
A single node template can cover all articles, while a specific file can restyle one content type or view mode. Use the smallest override that solves the problem to reduce upkeep. Twig escapes output by default, which helps prevent broken markup and cross-site scripting. Filter text only when needed, and keep complex logic in preprocess rather than in the template.
What belongs in a Drupal 11 theme?
A theme needs an info file that names it, declares regions, and lists libraries. A libraries file attaches CSS and JavaScript in defined groups, so pages load only what they use. Templates live in a templates folder, often grouped by content, blocks, fields, and pages.
Start from a stable base theme and override only the files you must change. Keep global styles for type, color, spacing, and buttons apart from component styles for cards, menus, and forms. Clear naming makes later edits faster for developers and project managers.
- Define regions for header, content, sidebar, and footer before adding templates
- Attach a small global library for base styles and separate libraries for heavy components
- Store one Twig file per component variation with a matching style partial
When should you use Layout Builder?
Layout Builder is the built-in tool that places sections and blocks on a page. It suits landing pages, homepages, and one-off layouts where order and width change often. Editors can add columns, place existing blocks, and adjust a single page without code. It is less useful when strict brand control matters across hundreds of similar pages.
Too many free-form sections can create uneven spacing, large pages, and harder upkeep. For repeated structured content, tuned content types and Views often stay cleaner than many hand-built pages. Set guardrails before enabling it widely. Offer a few approved section styles, limit who can create new layouts, and lock key templates such as headers and footers.
How do you build a custom block for theming?
A custom block is a reusable content unit with its own fields and template. Use a block type for editor-managed content such as promos, staff profiles, or alerts. Use a coded block plugin when the output comes from logic, such as nearby stores or related content.
Build the fields first, then shape the markup in a block Twig template. Keep fields plain and few, then handle style, spacing, and responsive behavior in CSS. Match the block markup to the design system so it looks right in any region or layout section.
- Create a block type with fields for title, text, link, and image
- Add one Twig template for that block type with clean markup
- Place it once through block layout or Layout Builder, then reuse it elsewhere
- Give editors help text for image size, link format, and title length
How do you keep a theme fast and maintainable?
Limit template overrides, reuse components, and remove unused libraries and styles. Large CSS files, many web fonts, and heavy sliders slow pages and hurt reading on phones. Small, shared patterns for headings, cards, and buttons are easier to test and restyle.
Check contrast, keyboard focus, heading order, and alt text in every custom template. Cache blocks sensibly so dynamic parts refresh while stable parts stay cached. Test the block in one layout before reusing it across many pages and templates.
