Starterkit theme

Description

This article serves as a comprehensive guide for developers looking to generate and manage custom themes in Drupal. It covers the step-by-step process of creating a new theme using Drupal’s command-line tools, customizing the theme’s directory path, and leveraging starterkit themes for enhanced customization. Additionally, the guide delves into tracking upstream changes to ensure your theme remains up-to-date with the latest improvements and bug fixes. It also provides detailed instructions on comparing different versions of starterkit themes and managing contributed projects.

Generating a new theme

A new theme named my_new_theme can be generated by running the following command from the Drupal root:

Note: If you are using web (or docroot) as a web-root add the web-root at the beginning of the script path: Example: web/core/scripts/drupal

php core/scripts/drupal generate-theme my_new_theme

This will write the theme to the themes/ directory by default. To change the directory run:

php core/scripts/drupal generate-theme my_new_theme --path themes/custom

Read the help text to see all configuration options:

php core/scripts/drupal generate-theme --help

and the result:

Description:
  Generates a new theme based on latest default markup.

Usage:
  generate-theme [options] [--] <machine-name>
  generate-theme custom_theme --name "Custom Theme" --description "Custom theme generated from a starterkit theme" --path themes
  generate-theme custom_theme --name "Custom Theme" --starterkit mystarterkit

Arguments:
  machine-name                     The machine name of the generated theme

Options:
      --name[=NAME]                A name for the theme.
      --description[=DESCRIPTION]  A description of your theme.
      --path[=PATH]                The path where your theme will be created. Defaults to: themes
      --starterkit[=STARTERKIT]    The theme to use as the starterkit [default: "starterkit_theme"]
  -h, --help                       Display help for the given command. When no command is given display help for the list command
  -q, --quiet                      Do not output any message
  -V, --version                    Display this application version
      --ansi|--no-ansi             Force (or disable --no-ansi) ANSI output
  -n, --no-interaction             Do not ask any interactive question
  -v|vv|vvv, --verbose             Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Custom starterkit theme

The starterkit theme command line tool supports using contrib and custom themes as a starting point. In order to be used as a starterkit theme, a theme named source_theme_name should:

• Make specific design decisions (e.g. default markup and CSS vs PostCSS).
• Ensure your theme has a source_theme_name.starterkit.yml file.

The *.starterkit.yml file informs the generate-theme command that the theme is a starterkit theme from which new themes can be generated and is also where the generate-theme command's behavior can be modified.

Configuring starterkit theme generation behavior

By default, the generate-theme command will loop through all files and filenames and do a string replace of the machine_name of the starterkit theme with the machine_name of the new theme. However, this behavior can be modified by declaring the following in the source theme's *.starterkit.yml file:

• ignore - Files to ignore (not copy over). Paths can be wildcards (e.g. *.yml) or globs (e.g. **/*.js). Entire directories can also be ignored (e.g. tests/**).
• no_edit - Files where the contents will not be edited. Paths can be wildcards (e.g. *.yml) or globs (e.g. **/*.js).
• no_rename - Files that will not have their filename renamed. Paths can be wildcards (e.g. *.yml) or globs (e.g. **/*.js).
• info - Additional properties that will be placed in the new theme’s info.yml file. Existing properties can be removed by giving them a null value.

An example of source_theme_name.starterkit.yml file's contents could look like the following:

ignore:
  - '/source_theme_name.starterkit.yml'
no_edit:
  - '/js/source_theme_name.js'
no_rename:
  - '/js/source_theme_name.js'
  - '/js/**/*.js'
info:
  version: 1.0.0

See the core Starterkit theme's starterkit_theme.starterkit.yml for an existing example implementation.

Generating a new theme from a contrib or custom starterkit theme

A new theme called my_new_theme can be generated using any contrib or custom starterkit theme (in this example, the source_theme_name starterkit theme) with following command:

php core/scripts/drupal generate-theme --starterkit source_theme_name my_new_theme

Defining additional post-processing for the generated theme

Starterkit themes can perform additional post-processing of the generated theme in a \Drupal\source_theme_name\StarterKit class that must implement \Drupal\Core\Theme\StarterKitInterface. See the core Starterkit theme for an example implementation.

Tracking upstream changes

Once you have generated a theme using Starterkit command, you may wish to track upstream changes in the Starterkit theme in order to incorporate upstream improvements and bug fixes into your theme. This is useful when you are maintaining a base theme that is based on a Starterkit theme.

Comparing versions of the core Starterkit theme

First, you will need to check which version of Starterkit was used to generate your theme. The starterkit theme command line tool stores information about the source that was used for generating the theme. This can be found from the my_new_theme.info.yml under generator key. For example, the following metadata indicates that a 10.2.4 version of the core starterkit_theme was used for generating the theme:

generator: starterkit_theme:10.2.4

With this information, it is possible to do a comparison between two versions using Git with the Drupal core repository. For example, to compare 10.1.2 and 10.2.4, use the following command on a clone of Drupal core:

git diff '10.1.2' '10.2.4' -- core/themes/starterkit_theme

The result will look like patch code:

diff --git a/core/themes/starterkit_theme/css/components/details.css b/core/themes/starterkit_theme/css/components/details.css
index a546363a29..04609fd48f 100644
--- a/core/themes/starterkit_theme/css/components/details.css
+++ b/core/themes/starterkit_theme/css/components/details.css
@@ -14,7 +14,7 @@ details {
 details > .details-wrapper {
   padding: 0.5em 1.5em;
 }
-/* @todo Regression: The summary of uncollapsible details are no longer
+/* @todo Regression: The summary of noncollapsible details are no longer
      vertically aligned with the .details-wrapper in browsers without native
      details support. */
 summary {
diff --git a/core/themes/starterkit_theme/templates/block/block--system-branding-block.html.twig b/core/themes/starterkit_theme/templates/block/block--system-branding-block.html.twig
index baa015b177..8814363c52 100644
--- a/core/themes/starterkit_theme/templates/block/block--system-branding-block.html.twig
+++ b/core/themes/starterkit_theme/templates/block/block--system-branding-block.html.twig
@@ -16,7 +16,7 @@
 {% block content %}
   {% if site_logo %}
     <a href="{{ path('<front>') }}" rel="home" class="site-logo">
-      <img src="{{ site_logo }}" alt="{{ 'Home'|t }}" />
+      <img src="{{ site_logo }}" alt="{{ 'Home'|t }}" fetchpriority="high" />
     </a>
   {% endif %}
   {% if site_name %}
...

Reviewing the list of theme changes by issue

If there are many changes between versions of a theme, or it's not clear which are important to add to your theme, you can review the list of individual changes and the issues that introduced them. To get a list of issues that have introduced changes, use the following command:

git log '10.1.2' '10.2.4' -- core/themes/starterkit_theme

Each of the changes include an issue number which represents a node in Drupal.org. With the node ID, it is possible to get full context of the issue by visiting https://drupal.org/node/[node_id]. For example, if the commit message begins with "Issue #1234567 by ....", the page to visit is https://drupal.org/node/1234567.

Comparing versions of a contributed project Starterkit theme

These commands also work for contributed projects using the Starterkit theme command. In this case you'll have to clone the contributed project with git, and run the same command without the path, e.g.:

git diff 1.0.0 1.5.0

git log 1.0.0 1.5.0