How Your Plugin Assets Work

Warning: We have not determined 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 images (like plugin headers, icons, and screenshots) used on your plugin’s display page.

All files should be placed into the assets directory of your SVN directory and will work for all versions of your plugin. This is a top level directory, just like trunk. You would not place the screenshots into trunk/assets or tags/1.0/assets.

Images can be in the JPG or PNG format (no animated GIFs, sorry).

All images are served through a CDN and cached heavily, so it may take a some time to update when changed or added. Please give the proxy some time to retrieve your images and cache them before reporting it’s not working. It should only take a few minutes, but 6 hours is not unheard of when the servers are under high load (like the week before and during a release of a major version of WordPress).

Plugin Headers Plugin Headers

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

Hello Dolly Header

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.

When designing your header image, keep in mind the use of international plugin directories. Some of these, like Hebrew and Arabic, use Right-To-Left (RTL) languages. In these cases, the title will be overlaid on the right hand side of the image, not on the left side. Design your banner such that the title can be in either position. As this may not work with all designs, you should create a different image for RTL pages with -rtl in the name.

Filenames Filenames

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

If RTL images are available, then they will be displayed on plugin pages in languages that use RTL. For example of an RTL image, look at Custom WP Login in English and then in Arabic.

For an example of Retina images, check out Hello Dolly or Pluginception. You cannot use the retina image alone, it only works as an “add-on” to the 772×250 image. The larger ‘retina’ image is only used on displays that can show the higher detail.

Top ↑

Plugin Icons Plugin Icons

Plugin icons are square images that show on the side of the plugin in searches on WordPress.org but also on the back-end of WordPress.org.

Akismet with it's Plugin Icon

In addition to JPG and PNG formats, you can also use SVG. Vectors are perfect for icons, as they can be scaled to any size and the file itself is small. 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.

If you do not use an icon, an auto-generated one will be made for you. Some examples are the circled icons below:

Example of auto-generated icons

Filenames Filenames

  • Normal: icon-128x128.(png|jpg)
  • High-DPI (Retina): icon-256x256.(png|jpg)
  • SVG: icon.svg

There are no plans to change these sizes.

Top ↑

Screenshots Screenshots

Screenshots show on the main page of your plugin, and are used to illustrate aspects of the plugin admin dashboard or live examples. There should be one screenshot for every line in your readme.txt file. The content of the lines will become the captions of the screenshots on your plugin’s page.

For example: 1. This is a monkey

That would show the caption ‘This is a monkey’ under the first screenshot. Presumably of a monkey.

Filenames Filenames

  • screenshot-1.(png|jpg)
  • screenshot-2.(png|jpg)

All filenames should be lowercase; uppercase names won’t work.

Top ↑

Issues Issues

If you find your images are downloading when people click on them from your WordPress.org Plugin Directory 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.