Generate a readme.txt for your WordPress plugins.
This plugin requires Grunt ~0.4.1
If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
npm install grunt-wp-readme --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt.loadNpmTasks('grunt-wp-readme');
In your project's Gruntfile, add a section named wp_readme
to the data object passed into grunt.initConfig()
.
grunt.initConfig({
wp_readme: {
options: {
readme: 'readme.txt',
defaultInstallation: '',
defaultFaq: '',
defaultChangelog: '',
defaultUpgrade: '',
defaultScreenshots: ''
},
your_target: {
displayName: '',
contributors: [],
donateLink: '',
tags: [],
minimumVersion: '',
testedUpTo: '',
stableTag: '',
license: 'GPL-2.0+',
licenseURI: 'http://www.gnu.org/licenses/gpl-2.0.html',
textDomain: '',
domainPath: '',
blurb: '',
sections: {
description: '',
installation: '',
faq: [],
screenshots: [],
changelog: [],
upgrade: '',
extra: {header: false, body: false}
}
},
},
});
Type: String
You can specify a custom location for the readme.txt file to be saved. By default, it will be saved to readme.txt
in the same directory as your Gruntfile.js
file. If the value you set for readme
doesn't end with readme.txt
, it is assumed to be a directory and will append /readme.txt
to the value.
Type: String
The default value of the Installation section if it is left undefined in your configuration
Type: String
The default value of the FAQ section if left undefined
Type: String
The default value of the Changelog section if left undefined
Type: String
The default value of the Upgrade Notice section if left undefined
Type: String
The default value of the Screenshots
Type: String
REQUIRED
Your plugin's display name
Type: Array
REQUIRED
An array of wordpress.org usernames. At least one must be specified.
Type: Array
Optional URL for donations
Type: Array
An array of tags to help people find your plugin
Type: String
REQUIRED
The minimum supported version of WordPress that your plugin works with
Type: String
REQUIRED
The version of WordPress up to which you've verified that your plugin works
Type: String
REQUIRED
The current stable version of your plugin.
Type: String
License under which your plugin is distributed. Defaults to GPL 2.0+
.
Type: String
Link to license text. Defaults to http://www.gnu.org/licenses/gpl-2.0.html
Type: String
The textdomain of the plugin for internationalization.
Type: String
The location of your translation files relative to the root directory of your plugin. If specified, it should have a leading slash.
Type: String
A short (preferably one sentence) description of your plugin
Type: Object
An object detailing the contents of any sections of the plugin's readme.txt
. See below for more details on sections and their structure/format.
Type: String
Longer description of plugin. Defaults to the value set in blurb
.
Type: String|Array
String or array of strings detailing installation instructions. If an array of strings is provided, they will be turned into an ordered list.
Type: Array
Array of faq objects. Faq objects must have a question
and answer
property. For example:
faq: [
{
question: 'What is this?',
answer: 'This is a FAQ sections!'
},
{
question: 'Do people really ask this with any degree of frequency?',
answer: 'No... :('
}
]
Type: Array
Array of screenshot captions. They will be added in the order in which they are given.
Type: Array
Array of changelog objects. changelog objects have the following properties:
- version Required Type:
String
. The version of the release being described - changes Required Type:
Array
. An array of changes made in this version. Will be turned into an unordered list. - releaseDate Optional Type:
String
. An optional date of release for the current version. If provided, it will be prepended to the unordered list of changes in this format:Released: {{date}}
. The format of the date doesn't really matter. It's just a string.
For example:
changelog: [
{
version: '1.0.1',
changes: [
'Fixed a fatal error caused by using the plugin',
'Started using grunt-wp-readme. ZOMG'
],
releaseDate: '1/17/2014'
},
{
version: '1.0',
changes: ['Initial release.'],
releaseDate: '2014-01-13'
}
]
Type: String
Upgrade notice contents
Type: Object
If your plugin has an extra arbitrary section of the readme, you can define the header and body of it here, using an object with a header
and body
property.
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.
- Initial release