WordPress插件 readme.txt 详解

为了使您在插件浏览器中的条目最有用，每个插件都应该有一个名为readme.txt的自述文件，该文件符合WordPress插件自述文件标准。此文件控制目录正面部分的输出。在自述文件中写一个描述可以准确地确定wordpress.org/plugins/Your-Plugin上显示的内容

您可以使用插件自述生成器，并将完成的结果通过官方自述验证器进行检查。如果您需要更多视觉帮助，可以使用工具wpreadme.com

由于WordPress 5.8插件自述文件没有根据需求进行解析。这意味着头Requires PHP和Requires至少将从插件的主PHP文件中解析。

所有插件都包含一个主PHP文件，几乎所有插件都有一个readme.txt文件。readme.txt文件旨在使用markdown的子集编写。

一个典型的插件readme.txt头部如下：

=== 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.

Contributors – 一个区分大小写、逗号分隔的列表，列出所有为代码做出贡献的WordPress.org用户名。通常认为，包括参与分支项目的人员的姓名是有礼貌的。一些开发人员会要求从列表中删除，因为他们不希望其他插件出现在他们的个人资料页面上。最好满足这些要求。记住只使用WordPress.org用户名——其他任何东西都会在没有个人资料链接和gravatar的情况下显示。要更改某人的显示名称（显示在插件的正面页面上），请编辑配置文件https://wordpress.org/support/users/yourid/edit/并更改显示名称。

Donate link – （可选）在侧边栏中创建“捐赠到此插件”链接。如果没有链接，则不会显示任何内容。

Tags - 描述插件的1到12个逗号分隔的术语。只有前五个会显示在生成的页面上，任何超过12个的内容都会对SEO不利。插件必须避免使用竞争对手的插件名称作为标签。

Tested up to - 插件经过测试的WordPress版本。此字段忽略次要版本，因为插件不应该随着次要更新而中断。这意味着插件只需要定义测试的主要版本，WordPress.org插件目录就会自动添加次要版本。这应该只是数字，所以“4.9”而不是“WP 4.9”

Requires PHP - （可选）与此插件一起使用所需的PHP的最低版本。这应该只是数字，所以“7.0”而不是“PHP 7.0”

Stable Tag - 插件的稳定版本。这不是WordPress的版本，而是插件本身的版本。仅使用数字和句点，建议使用SemVer格式。

License - 用于插件的GPLV2（或更高版本）兼容许可证。

License URI - （可选）到许可证的链接。这是可选的，但如果插件使用更罕见的许可证，强烈建议使用。

在标题部分的末尾是一个插件的简短描述。该示例建议不超过150个字符，并且不使用标记。这行文本是插件的单行描述，显示在插件名称的正下方。如果它的长度超过150个字符，它就会被剪掉，所以保持短。

安装

如果你的插件没有自定义安装设置，可以省略这一部分。如果你的插件在安装后有自定义的配置说明，这是一个放置这些信息的好地方。

自定义分区

虽然允许并支持自定义部分，但请适度使用它们。人们习惯于看到其他插件的外观，当你的插件很奇怪时，他们会错过重要信息。

Readme是如何解析的

虽然使用trunk的稳定标签目前在插件目录中有效，但它不是一种受支持或推荐的指示新版本的方法，并且已知会导致自动更新的问题。目前，我们正在积极劝阻并（在新插件的情况下）禁止使用它

WordPress.org的插件目录基于自述文件中稳定标签字段中的信息工作。当WordPress.org解析readme.txt时，它所做的第一件事就是查看/trunk目录中的readme.txt，在那里它读取“稳定标签”行。

当稳定标签设置正确后，WordPress.org将在/tags/中查找引用的版本。因此，“1.2.3”的稳定标签将使其查找/tags/1.2.3/。

标签文件夹中的readme.txt也必须正确更新，以获得正确的“稳定标签”——否则可能导致插件不可更新。

如果Stable Tag为1.2.3并且/tags/1.2.3/存在，那么系统的任何部分都不会进一步读取trunk中的任何内容进行解析。如果你试图在/trunk/readme.txt中更改插件的描述，那么你的更改对插件页面没有任何作用。所有内容都来自稳定标记所指向的文件中的readme.txt。

WordPress.org插件目录读取主插件PHP文件，以获取插件名称、插件URI等信息，最重要的是，还有版本号。在插件页面上，你会看到下载按钮，上面写着“下载1.2.3版”或类似的内容。这个版本号来自插件的主PHP文件，而不是自述文件！

Stable Tag指向/tags目录中的一个子目录。但插件的版本实际上并不是由该文件夹名称设置的。相反，插件的PHP文件中列出的版本本身决定了名称。如果你已经将Stable Tag更改为1.4，并且插件在PHP文件中仍然显示1.3，那么列出的版本将是1.3。

视频

默认情况下，您可以从YouTube、Vimeo和WordPress支持的任何其他地方嵌入视频。你所要做的就是将视频URL粘贴到你的自述文件中它自己的行上。

我们建议您不要将视频作为常见问题部分的最后一行，因为有时格式会变得奇怪。

Markdown

自述文件使用Markdown的自定义版本。大多数Markdown电话都能正常工作。

Markdown也允许在readme.txt中轻松链接。只需这样写即可将单词链接到URL：

[WordPress](http://wordpress.org)

视频也可以放进你的readme.txt中。一条线上的YouTube或Vimeo链接将自动嵌入。也可以使用wpvideo短代码嵌入VideoPress上托管的视频。

字段详情

对于那些想知道什么被解析为什么的人来说：

Authors

插件头中的Author字段和自述文件中的Contributors字段。

Version

插件头中的Version字段。

Tags (as in categories)

自述文件中的Tags字段。

Plugin Name

自述文件中的插件名称位于插件标头中指定的插件名称上。

Author and Plugin Homepages

插件头的作者URI和插件URI字段。插件URI对于每个插件都应该是唯一的。不要为您的免费和专业插件使用相同的URI。结局很糟糕。

Last updated time

版本号更改后最后一次签入相应目录的时间。

Creation time

创建时间。

文件大小

虽然自述文件是简单的文本文件，但文件大于10k可能会导致错误。你的自述应该简明扼要。描述不应该是推销，而应该是对插件、功能和使用方法的描述。你的安装方向应该是直接的。您的常见问题解答实际上应该解决问题。

至于您的变更日志，我们建议将当前版本保留在自述文件中，并将其余部分拆分到自己的文件中，例如changelog.txt。通过将所有旧的变更日志数据存储在那里，您可以使自述文件保持较小，并允许真正进入长变更日志的人自己阅读内容。

同样，如果您需要具有内联图像等的深入文档，请将人员引导到您自己的网站。