本文档介绍了 WordPress 插件目录中 readme.txt 文件的标准和重要性，该文件控制插件在前端目录的显示。自 WordPress 5.8 起，插件要求信息从主 PHP 文件解析，而非 readme.txt。
This page will explain some aspects of the plugin directory, and explain of the more obvious aspects which a lot of people miss.
To make your entry in the plugin browser most useful, each plugin should have a readme file named readme.txt that adheres to the WordPress plugin readme file standard. This file controls the output on the front-facing part of the directory. Writing a description in the readme determines exactly what will be displayed on wordpress.org/plugins/Your-Plugin
You can use the plugin readme generator and put your completed result through the official readme validator to check it. If you need more visual assistance you can use the tool wpreadme.com
Since WordPress 5.8 plugin readme files are not parsed for requirements. This means that headers Requires PHP and Requires at least are going to be parsed from plugin’s main PHP file.
All plugins contain a main PHP file, and almost all plugins have a readme.txt file as well. The readme.txt file is intended to be written using a subset of markdown.
The Plugin readme header consists of this information:
<pre class="wp-block-syntaxhighlighter-code">=== Plugin Name ===
Contributors: (this should be a list of wordpress.org userid's)
Donate link: https://example.com/
Tags: tag1, tag2
Requires at least: 4.7
Tested up to: 5.4
Stable tag: 4.3
Requires PHP: 7.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Here is a short description of the plugin. This should be no more than 150 characters. No markup here.</pre>https://wordpress.org/support/users/YOURID/edit/ and change the display name.At the end of the header section is a place for a short description of a plugin. The example recommends no more than 150 characters and to not use markup. That line of text is the single line description of the plugin which shows up right under the plugin name. If it’s longer than 150 characters, it gets cut off, so keep it short.
If your plugin has no custom install settings, it’s okay to omit this section. If your plugin has custom configuration notes post install, this is a great place to put that information.
While custom sections are permitted and supported, please use them in moderation. People get used to seeing how every other plugin looks, and when yours is weird, they’ll miss important information.
While most of the readme details are self evident, there are a few sections that trip people up.
WordPress.org’s Plugin Directory works based on the information found in the field Stable Tag in the readme. When WordPress.org parses the readme.txt, the very first thing it does is to look at the readme.txt in the /trunk directory, where it reads the “Stable Tag” line.
When the Stable Tag is properly set, WordPress.org will go and look in /tags/ for the referenced version. So a Stable Tag of “1.2.3” will make it look for /tags/1.2.3/.
If the Stable Tag is 1.2.3 and /tags/1.2.3/ exists, then nothing in trunk will be read any further for parsing by any part of the system. If you try to change the description of the plugin in /trunk/readme.txt then your changes won’t do anything on your plugin page. Everything comes from the readme.txt in the file being pointed to by the Stable Tag.
The WordPress.org Plugin Directory reads the main plugin PHP file to get things like the Name of the plugin, the Plugin URI, and most importantly, the version number. On the plugin page, you’ll see the download button which reads “Download Version 1.2.3” or similar. That version number comes from the plugin’s main PHP file, not the readme!
The Stable Tag points to a subdirectory in the /tags directory. But the version of the plugin is not actually set by that folder name. Instead, it’s the version that is listed in the plugin’s PHP file itself which determines the name. If you have changed Stable Tag to 1.4 and the plugin still says 1.3 in the PHP file, then the version listed will be 1.3.
trunk (rather than a version) still works in the Plugin Directory, it is neither supported nor recommended as a method of indicating new versions, and has been known to cause issues with automatic updates. We are currently actively discouraging the use of “Stable Tag: trunk” and prohibiting its use for new plugins.You can embed videos from YouTube, Vimeo, and anywhere else WordPress supports by default. All you have to do is paste the video URL onto it’s own line in your readme.
We recommend you NOT have the video as the final line in a FAQ section, as sometimes formatting gets weird.
The readmes use a customized version of Markdown. Most Markdown calls work as expected.
Markdown allows for easy linking in your readme.txt as well. Just write like this to link a word to a URL:
[WordPress](http://wordpress.org)
Videos can be put into your readme.txt too. A YouTube or Vimeo link on a line by itself will be auto-embedded. It’s also possible to embed videos hosted on VideoPress using the wpvideo shortcode.
For those who want to know exactly what gets parsed into what:
While readmes are simple text files, having a file larger than 10k may result in errors. Your readme should be brief and to the point. The description should not be a sales pitch as much as a description of the plugin, what it does, and how to use it. Your install directions should be direct. Your FAQ should actually address issues.
As for your changelog, we recommend keeping the current release in the readme and splitting the rest out out into it’s own file — changelog.txt for example. By storing all the older changelog data there, you keep your readme small and allow the people who get really into long changelogs to read things on their own.
Similarly, if you need in-depth documentation with inline images and so on, direct people to your own website.