Mercury Theme

Mercury is a component-based Drupal theme built with Tailwind CSS, providing a modern and flexible starting point for site owners to build scalable and efficient websites using Drupal Canvas.

Getting started

Mercury is designed to be copied, rather than used as a contributed theme or base theme, and you should not assume that future updates will be compatible with your site.

The steps to create a customizable theme depend on how your site started.

With a site template

If you are using Mercury with a site template and want to make customizations, you will need to convert Mercury to a custom theme with the same machine name.

If you change the machine name, any components provided by the site template will not work as expected.

You can maintain the machine name by running the following at the command line, from the Drupal project root (assuming web is the web root):

mkdir -p web/themes/custom
cp -R web/themes/contrib/mercury web/themes/custom/mercury
git add web/themes/custom/mercury
composer remove drupal/mercury

Finally, clear Drupal's cache (via the UI, or drush cache:rebuild).

Without a site template

If you want to use Mercury on a fresh install, you can install it via Composer, like any other Drupal theme.

To create the clone to use for your site, use Drupal core's starter kit tool:

cd drupal/web
php core/scripts/drupal generate-theme my_theme --name="My Custom Theme" --description="A customized version of Mercury." --starterkit=mercury

This will create a copy of Mercury called my_theme, and place it in themes/my_theme. This theme is yours, and you can customize it in any way you see fit!

To install it in Drupal, either visit the /admin/appearance page, or run drush theme:enable my_theme at the command line.

You can then remove the contributed version via Composer with composer remove drupal/mercury.

Sub-theming

Don't create your custom theme as a sub-theme of Mercury. Mercury is meant to be used as a starter kit, and does not provide backward compatibility. This allows us to rapidly innovate, iterate, and improve. If you create a sub-theme of Mercury, it is likely to break in the future.

For more technical information about how to build a custom theme based on Mercury, see the project README.

Getting help

If you have trouble or questions, please visit the issue queue or find us on Drupal Slack, in the #drupal-cms-support channel.

Roadmap

Mercury is under active development. Planned improvements include more components, better customization options, and Storybook support. If you want to contribute to Mercury, check out the #drupal-cms-development channel in Drupal Slack.