Drupalwoo ☉

Overriding Drupal core templates in a subtheme

Drupal builds most of its page structure from Twig templates supplied by core modules, the active theme and any parent theme. When a design calls for different markup, the safe approach is to override that template inside a subtheme rather than editing Drupal core. The override keeps custom behaviour together, is not overwritten during core updates and gives editors a clear place to review changes.

A successful override starts by identifying the actual template in use. A page can be assembled from node, block, region, form and page templates, while display modes add more specific alternatives. Understanding theme hooks and template suggestions lets you change only the component that needs it, avoiding a broad rewrite of a page that already works.

Australian development teams often work across Melbourne, Brisbane, Sydney and Perth, so a reproducible subtheme is useful beyond the machine that created it. Australian English, day-first dates and local handovers such as “Let’s catch this before arvo” are familiar signs of an Australian project, but none of those conventions should leak into generic HTML unless the content requires them.

This guide covers the practical route: create a child theme, copy the precise template, adjust its Twig safely, expose variables where appropriate and test the result. The examples use current Drupal 10 and 11 conventions, but the same hierarchy applies when a site still uses an older supported branch.

Why template overrides belong in a subtheme

Theme inheritance is the foundation of this technique. A subtheme declares its parent in its info file and inherits templates, assets, settings and preprocessing that it does not replace. Anything added directly to core/ or the parent theme becomes difficult to deploy and may be overwritten during an update. The child theme acts as the stable, project-specific layer.

Separate structural changes from presentational ones. Change Twig when the element itself must differ, such as replacing a wrapper or changing the order of semantic regions. Use preprocess functions for calculated variables and CSS for colours, spacing and typography. If existing markup already supports the design, a stylesheet override is usually less fragile than copying a template.

This separation also improves handover. A content editor can see that a heading change came from a template, while a front-end developer can inspect styles without untangling Twig. It also preserves Drupal behaviours such as contextual links, form tokens and view-mode classes, all of which can break when hand-written markup replaces the original render arrays.

Prepare a Drupal subtheme for local development

Start with a minimal theme and add only what the project needs. Create web/themes/custom/australian_civic/ and add an info file such as:

name: 'Australian Civic'
type: theme
base theme: olivero
description: 'A project-specific Drupal subtheme.'
core_version_requirement: '^10 || ^11'

Replace olivero with the theme your site actually uses; a starter theme may already provide templates you intend to refine. A minimal info file is enough to install the theme, but keeping templates/, css/, js/, australian_civic.theme and australian_civic.libraries.yml together makes ownership obvious.

Give every override a deliberate path. Generic node markup can start at templates/node.html.twig, while block and region alternatives can live under their corresponding template directories. The exact path is dictated by the theme hook and suggestions, so do not create a tidy directory that Drupal cannot discover. Clear caches after installation and use the same Drupal version across local and continuous integration environments.

For teams hosting Australian audiences, an origin around Sydney can reduce network latency, although the development workflow matters more than geography. Configure the site timezone deliberately: Brisbane and Perth do not observe daylight saving, while Sydney and Melbourne do. Test date output in UTC, Australia/Brisbane, Australia/Sydney and Australia/Perth when editorial schedules depend on local time.

Locate and copy the exact core template

Find the source from the site that is actually running, not from a generic tutorial. Core modules place templates under core/modules/*/templates/, while themes place them under core/themes/*/templates/ or a custom theme’s equivalent directory. The Devel module’s template suggestions, Twig debugging or drush theme:debug can reveal the winning template and its alternatives for a particular node or block.

Copy only the candidate you need, retain its filename and place it where the subtheme’s lookup will find it. A node suggestion might be node__article.html.twig or node--type-article--view-mode-teaser.html.twig; the latter applies only to that content type and display mode. If the parent theme already owns that suggestion, its copy can still win, so copying the precise alternative is safer than creating an unrelated generic file.

For example, the following override keeps Drupal’s title prefix, title suffix and rendered content while changing the wrapper:

<article{{ attributes.addClass('content-card') }}>
  {{ title_prefix }}
  {% if label %}
    <h2{{ title_attributes.addClass('content-card__title') }}>
      {{ label }}
    </h2>
  {% endif %}
  {{ title_suffix }}
  {{ content }}
</article>

Keep {{ content }} when it carries a render array, because it contains more than visible text. Preserve attributes and title hooks so JavaScript, contextual links and administrative controls continue to work. Compare the copied template with its source after every core upgrade; changed variables or removed markup should be handled deliberately rather than hidden by an old override.

Extend Twig variables without fragile markup

Variables are usually safer to change in a preprocess function than by rewriting core Twig. Place the function in australian_civic.theme and use the subtheme machine name as its prefix:

function australian_civic_preprocess_node(&$variables) {
  $node = $variables['node'];
  $variables['attributes']['class'][] = 'node--' . $node->bundle();
}

This adds a content-type class without replacing the node template. Preprocessing is useful for values that require PHP logic, Drupal APIs or configuration. It is less suitable for simple presentational decisions, which can remain in Twig or CSS.

For fields that should be resolved from the current entity, Drupal already supplies many values as variables. The site’s dynamic content tokens notes explain how replacement fields are assembled for broader editorial use; use those concepts to identify the required value, but consume the variable in Twig rather than reproducing token parsing inside a template.

For visual work, declare assets in australian_civic.libraries.yml and attach the library through a preprocess function. This keeps selectors and scripts connected to the theme and lets Drupal aggregate them with other assets. When the requirement is a genuinely new reusable component, register a theme hook with hook_theme(), place its Twig file in the subtheme and pass all content through explicit variables instead of reaching into global state.

Test, compare and maintain the override

Rebuild Drupal’s cache and inspect the rendered page rather than trusting the Twig file alone. Check the selected template, class names, heading order, mobile widths and keyboard focus. Test every affected display mode, including teaser and full views, plus empty results, anonymous access and permission-restricted content. A regression in a shared region template can affect pages far from the component being edited.

Because templates shape landmarks and form markup, WCAG 2.2 AA is a common acceptance target for Australian government, education and corporate work. Preserve skip links, the main landmark, visible labels, error relationships and meaningful link text. If the override wraps a form handling personal information, also consider the Australian Privacy Act and Australian Privacy Principles rather than changing required fields or consent wording casually.

For a release that crosses several agencies or authors, an independent pass by nFocus Software Testing can catch assumptions that a component author no longer sees. An external perspective is particularly useful for combinations of content types, display modes and permission roles that are easy to omit from a local build.

Choose the least invasive method that satisfies the requirement:

Method Best fit Main trade-off Usual location
Copied core template New semantic structure Requires upgrade reviews Subtheme templates
Parent-theme template Targeted parent markup Tied to parent naming Matching subtheme path
Preprocess function Added or calculated variables Introduces PHP logic Subtheme .theme file
CSS override Visual styling only Specificity and source order Subtheme stylesheet
Custom theme hook Reusable new component More setup and testing Theme hook and Twig template

Record the source template, Drupal version and reason for each override in the project repository. Recheck template suggestions after upgrades and remove redundant copies once the parent theme provides the required markup. That discipline keeps the subtheme small, makes regressions easier to trace and gives Australian teams a consistent site regardless of which city or developer performs the next release.