Crafting a Stunning LocalGov Drupal Sub-Theme: A 2025 Guide

Ready to make your LocalGov Drupal website shine? This guide is your passport to creating a beautiful, custom sub-theme! LocalGov Drupal gives you awesome building blocks, but sub-themes let you put your unique stamp on things *without* messing with the core. Think of it like adding a custom paint job to a super-reliable car. Inspired by Jim Kaufmann's insightful work, we'll walk through building your sub-theme the right way, avoiding common headaches along the way.

Why Go Sub-Theme? It's a Game Changer!

Seriously, if you're customizing LocalGov Drupal, a sub-theme isn't just recommended, it's essential. Here's why:

• Update-Proof Your Design: Core updates are a breeze. Your custom look stays put because you're not directly editing the main theme. Think of it as future-proofing your hard work!
• Super Organized Customization: All your tweaks live in one place. No more hunting through mountains of code! This means easier maintenance and faster changes.
• Brand Consistency Across the Board: Re-use your amazing sub-theme on multiple LocalGov Drupal sites. Keep your branding sharp and consistent across your entire organization.
• Plays Well with LocalGov Drupal: Sub-themes keep you in line with best practices, ensuring everything works smoothly with the platform.

Before You Dive In: The Toolkit

Make sure you've got these essentials ready:

• A Working LocalGov Drupal Site: Gotta have something to build on!
• Drupal Basics: A little understanding of Drupal themes (Twig templates, CSS, libraries) goes a long way.
• Your Favorite Code Editor: VS Code, Sublime Text, Atom... whatever makes you happy.
• Command Line Access: Time to get friendly with your Drupal installation's command line.
• YAML Power: YAML is how Drupal configures things, especially your sub-theme's .info.yml file.

Let's Build! Step-by-Step Sub-Theme Creation

Ready? Let's create your awesome LocalGov Drupal sub-theme:

1. Create a Home for Your Theme

Inside your Drupal installation's themes/custom directory, create a new folder for your sub-theme. Give it a unique, descriptive name. Something like department_theme is perfect if it's for a specific department.

mkdir web/themes/custom/department_theme

2. The All-Important .info.yml File

This file is the key! It tells Drupal everything about your theme: name, description, dependencies, etc. Create department_theme.info.yml (or whatever you named your folder) inside themes/custom/department_theme. It should look like this:

name: Department Theme
type: theme
description: A custom theme for the Department website.
core_version_requirement: ^9 || ^10
base theme: localgov_theme

libraries:
  - department_theme/global-styling

regions:
  header: Header
  primary_menu: 'Primary menu'
  secondary_menu: 'Secondary menu'
  content: Content
  sidebar: Sidebar
  footer: Footer

Let's break it down:

• name: The name people will see for your theme.
• type: Yep, it's a theme!
• description: A quick summary of what your theme is all about.
• core_version_requirement: Which Drupal versions your theme supports.
• base theme: CRITICAL! This tells Drupal your theme is a sub-theme of localgov_theme.
• libraries: Links to your CSS and JavaScript (we'll create those next).
• regions: The areas of your site where you can drop blocks (header, footer, etc.).

3. Define Your Libraries: .libraries.yml

This file tells Drupal about your CSS and JavaScript. Create department_theme.libraries.yml inside themes/custom/department_theme:

global-styling:
  version: 1.x
  css:
    theme:
      css/style.css: {}

This sets up a global-styling library that includes style.css from your theme's css directory.

4. CSS Time! Create the CSS Directory and style.css

Create a css directory inside themes/custom/department_theme, and then create the style.css file within it. This is where you'll add your custom CSS to make your LocalGov Drupal site truly unique.

mkdir web/themes/custom/department_theme/css
touch web/themes/custom/department_theme/css/style.css

Let's add some basic CSS to make sure everything's working:

body {
  background-color: #f0f0f0;
}

h1 {
  color: navy;
}

5. Enable Your Masterpiece!

Go to the Appearance page in Drupal (/admin/appearance). Find your sub-theme and click "Install and set as default".

If you don't see your theme, clear Drupal's cache. You can do this in the admin interface (Performance) or using Drush: drush cr.

6. Customize, Customize, Customize!

With your sub-theme active, it's time to unleash your creativity! Override CSS styles, tweak Twig templates, and add custom JavaScript.

Overriding CSS Styles

Add your styles to style.css. Be specific with your CSS selectors to avoid accidentally changing things you don't want to. Use your browser's developer tools (Inspect Element) to find the right selectors.

Overriding Twig Templates

Copy the template file from the core LocalGov Drupal theme to your sub-theme, keeping the same directory structure. For example, to change how nodes (content items) look, copy themes/contrib/localgov_theme/templates/content/node.html.twig to themes/custom/department_theme/templates/content/node.html.twig.

Drupal uses a smart naming system for templates. Use theme suggestions for even more control. For example, node--article.html.twig will *only* change the look of article nodes.

Remember to clear Drupal's cache after changing Twig templates!

Adding Custom JavaScript

Create a JavaScript file in your sub-theme's js directory and tell Drupal about it in your .libraries.yml file. For example, for a file named script.js, add this to department_theme.libraries.yml:

global-styling:
  version: 1.x
  css:
    theme:
      css/style.css: {}
  js:
    js/script.js: {}

Then, create the js directory and your script.js file:

mkdir web/themes/custom/department_theme/js
touch web/themes/custom/department_theme/js/script.js

Don't forget to clear Drupal's cache after adding or changing JavaScript files.

Sub-Theme Pro Tips

• Keep it Lean: Only override what you need to. The less you change, the easier it is to maintain.
• Be Specific with CSS: Avoid unintended consequences!
• Follow Drupal's Style Guide: Clean, consistent code is happy code.
• Git is Your Friend: Track changes and collaborate like a pro.
• Test, Test, Test: Make sure your theme looks great on all devices and browsers.
• Document Your Code: Help your future self (and others!).
• Modules First: See if a Drupal module already does what you need before writing custom code.
• Stay Up-to-Date: Keep your LocalGov Drupal and Drupal core versions current for security and compatibility.

Common Sub-Theme Mistakes (and How to Avoid Them)

• Never, EVER Touch Core Files: Seriously, don't.
• CSS Complexity: Keep your CSS simple and manageable.
• Ignoring Accessibility: Make sure your site is usable for everyone (WCAG guidelines are your friend!).
• Performance Problems: Optimize your CSS and JavaScript for speed. No one likes a slow website.
• Skipping Testing: Test on different devices and browsers.
• Forgetting the Cache: Always clear Drupal's cache after making changes!

Wrapping Up

Creating a sub-theme for your LocalGov Drupal website is the best way to customize its look and feel. By following these steps and best practices, you can build a maintainable, reusable, and compliant theme that makes your site stand out. Happy theming!