Starterkit theme

Last updated on

16 March 2024

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 web at the beginning of the script path: Ex: 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).
Add a line containing starterkit: true to the theme’s source_theme_name.info.yml file.

A new theme called my_new_theme can be generated using any custom starterkit theme with following command:

php core/scripts/drupal generate-theme --starterkit source_theme_name my_new_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.0.7 and 10.1.2, 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 diff '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.: