Start with a subtheme based on a default theme and learn to override Twig templates and attach your own CSS and JavaScript. Drupal theming is the layer that controls how your site looks and how content turns into HTML, using themes made of templates, styles, and settings.
A theme does not store your content. It decides where content appears, what markup wraps it, and which styles and scripts load. That separation lets you change design without editing content or site logic.
Table of Contents
- How does a Drupal theme work?
- Which starting point should a beginner choose?
- How do you override a template?
- Where do CSS and JavaScript belong?
- What workflow prevents common mistakes?
How does a Drupal theme work?
A theme is a folder with an info file, templates, CSS, JavaScript, and configuration. Drupal reads the info file to list the theme on the Appearance page. Templates shape the HTML for pages, blocks, fields, and views. Most markup comes from Twig files, which mix simple placeholders with HTML.
Regions divide the page into areas like header, content, and footer. Blocks fill those regions, and display settings control field order. CSS and JavaScript load through named libraries defined by the theme. You attach a library to the whole theme, to certain templates, or to specific pages. This keeps assets organized and avoids loading unused code.
Which starting point should a beginner choose?
Copy a default theme into a subtheme rather than editing the original. A subtheme inherits markup and styles from its parent, so updates to the parent do not erase your work. This is the safest way to learn.
Place your custom theme in the site themes folder for locally added code. Keep the theme name short, lowercase, and without spaces. Use the default parent theme at first, then explore contributed base themes once you know the basics.
- Create one custom subtheme for practice.
- Activate it on a test site before touching a live site.
- Change one element at a time, such as colors, logo, or header layout.
- Keep notes on each override so you can undo mistakes.
How do you override a template?
Template overrides let you change HTML for one part of the site without copying the whole theme. Turn on template suggestions during development to see which template names Drupal checks for each area. Choose the most specific name that matches only what you want to change. Copy the original template into a templates folder inside your theme and rename it to the suggested name.
Edit the copy, save, and clear the cache to see the result. Keep the original logic intact unless you have a clear reason to change it. Common first overrides include page layout, node display, and block wrappers. Start with small edits like adding a wrapper class or moving a title. Test each change on desktop and mobile before moving on.
Where do CSS and JavaScript belong?
Put styles and scripts in your theme and register them in its libraries file. Each library lists CSS files, JavaScript files, and dependencies it needs to run. Attaching a small, focused library prevents conflicts and speeds loading. Use custom CSS for colors, fonts, spacing, and layout adjustments.
Use JavaScript only for behavior that CSS cannot handle, such as menus, sliders, or interactive filters. Keep theme scripts separate from content scripts added by editors. Clear the cache after changing library definitions. If styles do not appear, check the library name, file path, and attachment point. Browser developer tools help confirm whether the file loaded.
What workflow prevents common mistakes?
Work on a local or staging copy and keep the theme in version control. Enable development settings locally so Twig templates rebuild on every page load. Disable those rebuilding options before launch for better performance. Never edit core themes or modules directly.
Your changes will disappear on update and become hard to track. Put every design change in your subtheme, even quick fixes. Learn to clear cache, check logs, and test permissions early. Many theming problems come from cached markup, missing file paths, or blocked access to theme settings. Fix one layer at a time: markup first, then CSS, then JavaScript.
