The definitive guide to the WordPress.org plugin assets folder

If you’ve ever added a plugin to the WordPress.org directory, you’ll find there’s a folder named assets waiting for you in SVN. In this article, I’m going to explore what you can add to this, and the various limitations and formats available to you.

Images

There are various types of images that can be placed within the assets folder, and all should be placed in the root of this folder – never in a sub-folder. In all cases, both PNG and JPG formats are available for use and filenames should be lower case.

Plugin Icons

These are the square icons that appear on the top left corner of your plugin directory listing. Between these and the banner, I think these are the more important to make sure you use, as they’re also used in search results too, and can add an immediate visual appeal to your plugin.

As well as JPG and PNG, you can also use SVG as well, which is certainly something that I’d recommend you use, if you can, due to the improved scalability of this format. However, if you do, you should include another format of icon too, in case the browser being used doesn’t support the SVG format (or it’s used on Facebook) – basically, the second format will be used as a backup.

If you don’t have an SVG for your icon, then I would highly recommend using Vectorizer.ai to generate one for you – this is what I’ve used for all of my plugin icons.

Icons are displayed at 128×128 pixel size. However, you can also specify a second icon at twice that resolution for retina screens (but you HAVE to include the standard resolution size icon too). It’s optional, but recommended.

The format for the icons are therefore…

icon-128x128.(png|jpg)
icon-256x256.(png|jpg)
icon.svg

1MB is the maximum file size for the icons.

Plugin Banners

These are displayed at the top of your plugin page. Unlike icons, they aren’t used elsewhere, however, and, in my opinion, are less important to have (I don’t use them myself).

Like icons you can specify both a standard and retina format (in this case 772×250 and 1544×500 pixels) but, unlike icons, you can’t use SVG. There are also 2 further types of variations available…

1. RTL (right-to-left). Not every language displays in a left-to-right format, so if you wish to add an RTL banner, simple add the suffix of -rtl to the end of your filename. This will be shown automatically if the users settings are set for an RLT language.
2. Localised. Yes, you can create a banner for a specific language – simple add a suffix of the locale code to the end. This can be the full or partial locale. For example, es or es_ES)

Based on this, there are the formats of the banner images (again, the second one is optional, but recommended, but the first one must always be included).

banner-772x250(-rtl|es|es_ES).(jpg|png)
banner-1544x500-(rtl|es|es_ES).(jpg|png)

You can’t specify both a localisation and RTL as you should consider the second a lesser version of the first.

Oh, and 4MB is the maximum file size for these files. For this reason use of the PNG format for these is not recommended.

Here’s an example of what the icon and banner looks like for the Jetpack plugin…

Screenshots

If you want to include screenshots along with your README, then this is where you put the actual screenshot images. The format of these is…

screenshot-1(-es|es_ES).(png|jpg)

As you can see, like banners, you can localise them too.

The suffix number (in this case -1) relates to the number used in the README for the corresponding description. For example, in your README you may have…

== Screenshots ==

1. The settings page

2. An example of the output that the previous settings would generate

So, you would need 2 screenshot images to go along with these, with the suffix of -1 and -2 to correspond with the descriptions. These descriptions are then used as the screenshot captions.

10MB is the maximum file size, so it’s probably best to avoid PNG for the format. Thumbnails are shown in the directory list (which are automatically generated) – wide, short screenshots are best avoided because they’ll be difficult to make out at this size. In all cases, clicking on a screenshot thumbnail will show it full size so also consider making sure, within the limitation of the file size, making sure that it’s big enough for any detail to be readable.

Again, using Jetpack as our example, here’s how their carousel of screenshots appears…

Playground Blueprint

A new addition has been added to the assets folder – Playground Blueprints. These are used to allow you to add a WordPress Playground button to your plugin listing, to allow potential users to try it out in their browser. This lives in a sub-folder named blueprint, and is the only time that a folder should be added to the assets.

For more detail on creating the blueprint file, please read my other article here.