Screen shot 2012-05-04 at 3.03.02 AM

Creating A WordPress Plugin Part 7: ReadMe.txt

May 4, 2012
155 Views

Okay so now that people can download the plugin, we should create some documentation for it to help them understand how to install and use the plugin.

Open up the readme.txt from your local copy of the SVN reposity’s trunk/ folder.

Also make sure to read the readme.txt standards example Here

The ReadMe.txt not only serves as instructions to the users, but it also gets transformed into information on the plugin page by wordpress. The way you write this file matters, so make sure to pay close attention to spaces!

let’s get started.

Basically you just start replacing the information in the example with your information. This is how mine ended up

=== Plugin Name ===
Contributors: kaser
Donate link: http://cssboss.com/donate
Tags: banner, image link, advertisement
Requires at least: 3.3
Tested up to: 3.3
Stable tag: 1.0
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html

Put A Banner image any where you want with ease!

Contributors: is a list of wordpress.org user names who all helped with the plugin. Since I am the only contributor of this plugin, I’ll just take all of the credit.

Donate link: just a link to a donate page if you have one. For people to show some love!!

Tags: a list of things that you can tag the plugin with.

requires at least: the lowest version of wordpress this plugin will work on. (mine will always be the latest version)

Tested up to: the latest version of wordpress you have tested this up to (again, mine will always be the latest version)

Stable Tag: this is the version folder you created in your tag folder. you want this to be the same as what you named the tag from the last tutorial.

License is standard GPLv2 or later and a uri.

Then finally, a short description to be used on the search results page when people are looking to install your plugins.

As you can see, my plugins page is pretty empty :

We can put all the instructions for the plugin right here, by placing it all into the readme.txt after the file header we just edited.

mine looks like this

== Description ==

This pluging simply allows you to link an image together with out the knowledge of html and simply be able to put the code where ever you want your image to show up.

* you can use it in a widget area
* you can use it in any area that accepts shortcodes
* you can even put it right into the template file itself!

pretty simple, but it will get me going.

Now we need to give installation instructions. This will create another tab on our plugins page for people to read.

== Installation ==

Here is how you work the Boss-Banner-Ad plugin

1. Upload the plugin folder boss/banner/ad/ to the wordpress plugins folder
1. Activate the plugin through the 'Plugins' menu in WordPress
1. For the template tag, place `<?php boss_banner('image_url.jpg','http://www.cssboss.com','100','100'); ?>` in your templates. the 3rd and 4th args are the width and height in pixels. 100px wide, 100px tall
1. For the widget, simply drag and drop the widget into a sidebar, and configure the URL's and sizes of the image.
1. For the shortcode, simply put [banner_ad link="http://www.cssboss.com" image="http://cssboss.com/wp-content/uploads/2012/02/cssbosslogo.png" width="100" height="100"]

Again, very basic and really straight forward. Our page is coming along, let’s get some FAQ’s on there ( I don’t have any yet, so I am just going to make a couple up)

== Frequently Asked Questions ==

= what does the template tag mean? =

you call the function of my plugin, banner_ad(), and supply 4 bits of data. The url to the image, the url you want the image to link to, the width of the image, and then the height of the image.

= does this plugin automatically generate the tags for you? =

Not in version 1.0... not yet ;)

So now that’s out of the way, we’re almost ready to wrap up. We need to take a couple of screen shots, and begin our “change log” so that we can keep track of the changes we make going into each version.

You have 4 options how you want to save your screen shots, as a .png, .jpg, .jpeg, or .gif

You have to name your images “screenshot-” and then the number screen shot it is. This is my screenshot-1.jpg

I can ad a description to this inside of the readme.txt by putting the corresponding number that is in the file name, on it’s own line inside the file. You can have as many images as you want, but I’m just going to start out with one and I’ll patch it up nicely later.

== Screenshots ==

1. This is the widget control panel of the Boss Banner Ad plugin

Make sure to put the images inside the plugin-name/ directory.

Now we just create the change log, at the bottom of the readme.txt. I’m going to keep it short since it’s the initial release. all future “changes” will be documented though.

== Changelog ==

= 1.0 =
* Initial Release. May 4th 2012.

Now let’s save that file and move onto the next thing! Here’s my final readme.txt

=== Plugin Name ===
Contributors: kaser
Donate link: http://cssboss.com/donate
Tags: banner, image link, advertisement
Requires at least: 3.3
Tested up to: 3.3
Stable tag: 1.0
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html

Put A Banner image any where you want with ease!

== Description ==

This pluging simply allows you to link an image together with out the knowledge of html and simply be able to put the code where ever you want your image to show up.

* you can use it in a widget area
* you can use it in any area that accepts shortcodes
* you can even put it right into the template file itself!

== Installation ==

Here is how you work the Boss-Banner-Ad plugin

1. Upload the plugin folder boss/banner/ad/ to the wordpress plugins folder
1. Activate the plugin through the 'Plugins' menu in WordPress
1. For the template tag, place `<?php boss_banner('image_url.jpg','http://www.cssboss.com','100','100'); ?>` in your templates. the 3rd and 4th args are the width and height in pixels. 100px wide, 100px tall
1. For the widget, simply drag and drop the widget into a sidebar, and configure the URL's and sizes of the image.
1. For the shortcode, simply put [banner_ad link="http://www.cssboss.com" image="http://cssboss.com/wp-content/uploads/2012/02/cssbosslogo.png" width="100" height="100"]

== Frequently Asked Questions ==

= what does the template tag mean? =

you call the function of my plugin, banner_ad(), and supply 4 bits of data. The url to the image, the url you want the image to link to, the width of the image, and then the height of the image.

= does this plugin automatically generate the tags for you? =

Not in version 1.0... not yet ;)

== Screenshots ==

1. This is the widget control panel of the Boss Banner Ad plugin

== Changelog ==

= 1.0 =
* Initial Release. May 4th 2012.

So there we go. Our readme.txt is all set (for now), Till the next step!

This is now what our page looks like

In his last 10 years as a freelance Web Designer / Developer, Andrew Kaser has achieved further than just a “higher understanding of creating symantec code while keeping resources low.” Kaser looks to help promote better web standards in order to build a flourished industry that exceeds current development practices.

1 Comments

  1. You can use the plugin readme.txt generator:

    http://GenerateWP.com/plugin-readme/

Leave A Comment