Export IntelliJ editor themes as plugins

Today, I’d like to highlight a small but very useful feature for IDEs based on the IntelliJ Platform – exporting editor colour schemes as plugins. That’s right, if you have a custom editor scheme defined, you can get your favourite IntelliJ-based IDE to export it as a plugin .jar file, complete with plugin metadata, and upload it directly to the Plugin Repository for others to install and enjoy.

For example, you can use the plugins dialog to search for and install the IdeaLight colour scheme, and you can browse all editor colour scheme plugins on the site.

IntelliJ-based IDEs have previously been able to share editor colour schemes by exporting as a .icls XML file, and you can (still) share and import these files manually, or through sites such as color-themes.com.

Exporting a colour scheme as a plugin is just as easy, but you get the additional benefits of being a standard IntelliJ Platform plugin – metadata, feedback, download statistics, and of course, versioning. If you want to update your scheme, you just upload a new version of the plugin to the Plugin Repository, and all your existing users will be notified that there is an update available.

How does it work?

Before we dive into details, what do I mean by “editor colour scheme”? Well, this isn’t the full look and feel of the IDE, such as the default IntelliJ theme, Darcula or the popular third party Material theme. Instead, this is the colours used just by the editor – the colours for syntax highlighting, but also for the editor background, adornments such as code folding and indent guide lines, and inline debugger values amongst others.

It’s very easy to export your plugin. Once you’ve created and edited a new scheme, usually by duplicating an existing scheme, you can click the settings cog icon in the Preferences | Editor | Colour Scheme page and select Export | Colour scheme plug-in .jar. 

Export colours as plugin jar file

The next thing you’ll see is a dialog asking for plugin metadata. Enter a version, a description and change notes, and then some vendor information – name, email and a URL for information about your plugin (GitHub, perhaps, or a site with screenshots of your scheme in action).

Enter plugin metadata dialog

Once you hit OK, you’ll be presented with a file chooser to pick where to export the file, and what to call it. Clicking OK again, and you’ll have a plugin .jar file which you can then easily upload to the Plugins Repository. Happy sharing!

If you wish to update your plugin with a new version that has some tweaks, simply export a plugin again – give it a new version, update the change notes and export. Then simply upload to the Plugins Repository as a new version.

When you do upload your plugin, make sure you add the “Editor Color Schemes” tag as we’re planning on adding a landing page just for colour schemes.

Under the hood

That’s all well and good, but this is the Platform blog, so let’s dive deeper. What does the plugin look like?

Since a .jar file is just a zip file, we can easily extract the contents and take a look. If we do, we’ll see that there are two files:

  • /META-INF/plugin.xml – contains standard plugin metadata.
  • /colors/My Darcula scheme.xml – the colour scheme itself. The filename will be different for each plugin, and is based on the name of the colour scheme defined in the IDE.

If we take a look at the plugin.xml file, we can see that’s it contains standard plugin metadata, compatibility requirements and registration for the colour scheme itself.

We can see the plugin’s ID and display name, generated from the name of the scheme in the IDE. It also includes version number, description, change notes and vendor details, as entered into the metadata dialog.

Compatibility requirements are handled with a minimum version of “142.0”, which means it’s compatible with any IDE since IntelliJ 15.0, released in November 2015 (142 was the build number of what became 15.0), and a dependency on the  com.intellij.modules.lang module, which means that this plugin only requires the IntelliJ Platform, and so will install into any IntelliJ-based IDE – IDEA, WebStorm, DataGrip, Rider and so on.

The most interesting part, however, is the contents of the extensions element. The plugin uses the bundledColorScheme extension point to specify a path, from the root of the .jar file, to a bundled colour scheme, and this points to our exported colour scheme.

While the user interface doesn’t support this, the bundledColorScheme extension point can be used multiple times, so a plugin can include more than one colour scheme, with all of the schemes appearing in the drop down for the user to choose. This isn’t supported by the user interface, but the generated plugin can be manually altered, and used as a starting point for creating a plugin that does contain multiple schemes, or even other functionality from other extension points.

Turning to the other file in the .jar, if we take a look into this, we can see that it’s a standard .icls  file, even though it has a .xml  extension.

The file contains more metadata – the name of the scheme, when it was created and so on, and it also contains various values – fonts and font sizes. And of course it contains the changed colour values. But because this theme is based on Darcula, only the changed colours are included in the file, and we can see that the root scheme element has a parent_scheme attribute pointing to Darcula.

Summary

Exporting a colour scheme as a plugin is a very easy way to export your colour scheme – just as easily as for a standalone .icls file. But it gives you a much richer means of distributing your colour scheme – as a plugin, with all of the benefits – ease of sharing on the Plugins Repository, appearing in the search in the Plugins preference, and best of all, notification and ease of install when you push a new version. If you have a custom colour scheme, give it a go!

This entry was posted in IntelliJ Platform, Plugin Repository and tagged , . Bookmark the permalink.

6 Responses to Export IntelliJ editor themes as plugins

  1. The main problem here is that we cannot import/export color scheme separately from other theme settings. When I import color scheme I just need color values, not fonts and other settings.

    • Matt Ellis says:

      Hi Dmitriy, I’ve raised an issue to allow import/export of colour schemes without including font information, please upvote and add any extra comments you have: IDEA-183149.

      However, it’s also very easy to ignore the scheme’s font settings – in the Editor | Colour Scheme | Colour Scheme Font and Editor | Colour Scheme | Console Font preference pages there are checkboxes to use the colour scheme font in preference to the default font. Uncheck these, and you’ll use the default font defined in the Editor | Font preference page.

  2. ankit patel says:

    Hi, I want to add suite extension as an (i.g. JAVA, Groovy, HTML,etc..) in color scheme. Can is it possible? because I made a test framework and I used a .suite file as well.
    And my wish is color should be used in .suite file.

    • Matt Ellis says:

      You can assign a file type to a new extension in the Preferences | Editor | File Types page. This page will show a list of file types, such as HTML. When you select one of these file types, you can then choose what file extensions map to it – you can add *.suite as a new pattern, and from then on the IDE will recognise any *.suite file as being of that file type and apply the appropriate syntax highlighting.

      Does that help?

  3. DANIEL PEACH says:

    Hi so what I have done is taken a theme I liked, edited it in intellij, and then exported it as my own custom.jar. But then when I go to import it again, it still is called the old theme’s name. I want it to be called my theme’s name. So I uncompressed it in Finder, opened it in VSCode, and did a search/replace for the old theme name to my theme’s name. But how do I get it back to a .jar now? I have tried to compress it and then rename it to .jar, but then when I try to import it, it says there is no color scheme found in that .jar file. What do I need to do here? Thanks! Also, I would think intellij should handle all this renaming for me, and it doesnt.

Leave a Reply

Your email address will not be published. Required fields are marked *