Export IntelliJ editor themes as plugins

Matt Ellis

Today, I’d like to highlight a small but very useful feature for IDEs based on IntelliJ Platform – exporting editor color schemes as plugins. That’s right, if you have a custom editor scheme defined, you can get your favorite 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 color scheme, and you can browse all editor color scheme plugins on the site.

IntelliJ-based IDEs have previously been able to share editor color 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 color 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 color 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 are the colors used just by the editor – the colors for syntax highlighting, but also for the editor background, adornments such as code folding and indent guide lines, and inline debugger values, among 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 | Color Scheme page and select Export | Color scheme plug-in .jar. 

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).

Once you click 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 color 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 color scheme itself. The filename will be different for each plugin, and is based on the name of the color 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 color scheme itself.

<idea-plugin>
 <id>color.scheme.My Darcula scheme</id>
 <name>My Darcula scheme Color Scheme</name>
 <version>0.1</version>
 <vendor email="matt.ellis@jetbrains.com" url="https://github.com/citizenmatt/MyDarculaScheme">Matt Ellis</vendor>

 <description><![CDATA[
 My color scheme, based on Darcula, but with added green.
 ]]></description>

 <change-notes><![CDATA[
 Several tweaks to make it more awesomer.
 ]]>
 </change-notes>

 <idea-version since-build="142.0"/>

 <depends>com.intellij.modules.lang</depends>

 <extensions defaultExtensionNs="com.intellij">
   <bundledColorScheme path="/colors/My Darcula scheme"/>
 </extensions>
</idea-plugin>

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 – IntelliJ 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 color scheme, and this points to our exported color 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 color 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.

<scheme name="My Darcula scheme" version="142" parent_scheme="Darcula">
  <option name="FONT_SCALE" value="1.0" />
  <metaInfo>
    <property name="created">2017-12-01T14:32:15</property>
    <property name="ide">idea</property>
    <property name="ideVersion">2017.3.0.0</property>
    <property name="modified">2017-12-01T14:32:17</property>
    <property name="originalScheme">My Darcula scheme</property>
  </metaInfo>
  <option name="EDITOR_FONT_SIZE" value="13" />
  <option name="EDITOR_FONT_NAME" value="Fira Code" />
  <option name="EDITOR_LIGATURES" value="true" />
  <option name="CONSOLE_FONT_NAME" value="Menlo" />
  <option name="CONSOLE_FONT_SIZE" value="12" />
  <attributes>
    <option name="TEXT">
      <value>
        <option name="FOREGROUND" value="a9b7c6" />
        <option name="BACKGROUND" value="42b0a" />
        <option name="EFFECT_TYPE" value="5" />
      </value>
    </option>
  </attributes>
</scheme>

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 color values. But because this theme is based on Darcula, only the changed colors 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 color scheme as a plugin is a very easy way to export your color scheme – just as easily as for a standalone .icls file. But it gives you a much richer means of distributing your color 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 color scheme, give it a go!

Subscribe to JetBrains Platform updates

Subscribe form

By submitting this form, I agree to the JetBrains Privacy Policy Notification icon

By submitting this form, I agree that JetBrains s.r.o. ("JetBrains") may use my name, email address, and location data to send me newsletters, including commercial communications, and to process my personal data for this purpose. I agree that JetBrains may process said data using third-party services for this purpose in accordance with the JetBrains Privacy Policy. I understand that I can revoke this consent at any time in my profile. In addition, an unsubscribe link is included in each email.

Submit

Thanks, we've got you!