How Your Plugin Assets Work

Warning: We have not announced the new banner sizes, so don’t try to be clever and change yours yet.

The assets folder in your plugin is where you can store plugin headers, icons, and screenshots.

All files should be placed into the assets directory of your SVN. Note that this is a top level directory, like trunk. You would not place the screenshots into trunk/assets.

Plugin Headers Plugin Headers

Plugin headers are those images you see at the top of a plugin page:

Hello Dolly Header

To create assets properly, you will need to upload the files to your plugin’s SVN directory with the path assets. We accept JPGs and PNGs (no animated GIFs, sorry). The filenames and sizes must match, and only properly named files will appear in the directory.

Consider is the case for the international plugin directories. Some of these, like Hebrew and Arabic, use Right-To-Left languages. In these cases, the title will be overlaid on the right hand side of the image, not on the left side. Generally it is best to design your banner such that the title can be in either position. However, this may not work with all designs, so if you need to have a different image for RTL pages, then you can do so. Make the images in the same way as before, but name them with -rtl appended to the name.

So an RTL banner would be named assets/banner-772x250-rtl.(jpg|png) and assets/banner-1544x500-rtl.(jpg|png). On RTL pages, if these images are available, then they will be displayed instead.

After you check in your new banner(s), it will appear the next time the plugin refreshes itself in the directory. This may take a few minutes.

For development and testing, you can add a URL parameter to your plugin’s URL of ?banner_url=A_URL_TO_YOUR_IMAGE to preview what the page will look like with your own image. This will only work with your own plugins; you cannot use this parameter on anybody else’s plugins.

The Current Directory Filenames: The Current Directory Filenames:

  • Normal Banner: banner-772x250.(jpg|png)
  • High-DPI (Retina): banner-1544x500.(jpg|png)

For an example of this in action, check out Hello Dolly or Pluginception for HiDPI action.

You can not use the retina image alone, it only works as an “add-on” to the 772×250 image, because this larger image is only used on displays that can show the higher detail.

Top ↑

The New Directory: The New Directory:

  • Banner sizes have not been finalized for the new plugin directory at this time.

Top ↑

Plugin Icons Plugin Icons

Akismet with it's Plugin Icon

Plugin icons are 128 pixels square. HiDPI (retina) icons are supported at 256 pixels square. Like banners, these go into your /assets directory and can be either a PNG or JPG.

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

You also have another option: SVG. Vectors are perfect for icons, as they can be scaled to any size and the file itself is small. For an SVG file, you simply need an assets/icon.svg file. If you chose to use SVGs, you must also use a PNG icon as a fallback, otherwise your plugin icon will not display properly in older browsers or on Facebook.

Top ↑

Screenshots Screenshots

Screenshots should be named assets/screenshot-1.png, assets/screenshot-2.png, and so on. One screenshot for every line in your readme.txt file. The lines in the readme.txt file in the Screenshots section will become the captions of the screenshots on your plugin’s page. JPG files are acceptable too. Note that all filenames should be lowercase, uppercase names won’t work.

Like everything else in the assets directory, we are serving the screenshots through a separate CDN, and so it may take a few minutes to update when you change them. What this means is that when you put the screenshots in there for the very first time, they may not show up on your page for a few minutes and you’ll just see the captions with no images above them. Please give the proxy some time to retrieve your screenshots and cache them before telling me it’s buggy. It should only take a few minutes.

Top ↑

Issues Issues

If you find your screenshots are downloading when people click on them from your WordPress.org Plugin Directory screenshot page, you’ll need to make a change in how you upload them via SVN. It’s due to how some images are sent with the Content-Type application/octet-stream.

To fix it, run this command:

svn propset svn:mime-type image/png *.png
svn propset svn:mime-type image/jpeg *.jpg

Alternatively, plugin authors can set this in their ~/.subversion/config file:

*.png = svn:mime-type=image/png
*.jpg = svn:mime-type=image/jpeg

That’ll apply to only new files though. Fixing already-committed files will require the command above.