本页面将解释插件目录的一些方面，并解释一些常被人们忽略的重要细节。

为了使您的插件在插件浏览器中获得最佳效果，每个插件都应该包含一个名为 readme.txt 的文件，该文件应符合 WordPress 插件 readme 文件标准。此文件控制目录前端部分的显示内容。在 readme.txt 文件中编写的描述将直接显示在 wordpress.org/plugins/Your-Plugin 页面上。

您可以使用 插件 readme 生成器 创建 readme.txt 文件，然后使用 官方 readme 验证器 检查其正确性。 如果您需要更直观的帮助，可以使用 wpreadme.com 工具。

自 WordPress 5.8 以来，插件 的 readme 文件不再用于解析需求。这意味着，Requires PHP 和 Requires at least 等信息将从插件的主要 PHP 文件中提取。

目录详情

所有插件都包含一个主要 PHP 文件，并且几乎所有插件都包含一个 readme.txt 文件。 readme.txt 文件应使用 Markdown 的一个子集编写。

Readme 文件头信息

插件 readme 文件头包含以下信息：

=== 插件名称 ===
Contributors：(应为 WordPress.org 用户 ID 的列表)
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 或更高版本
License URI：https://www.gnu.org/licenses/gpl-2.0.html
这是一个插件的简短描述。 此描述不应超过 150 个字符。 不得包含任何标记。
  • Contributors – 这是一个区分大小写的、以逗号分隔的列表，包含所有为插件代码做出贡献的 WordPress.org 用户名。 通常，建议包含参与分叉项目的开发者的姓名。 有些开发者可能会要求从列表中删除他们的姓名，因为他们不想在自己的个人资料页面上显示其他插件。 务必遵守这些请求。 请务必仅使用 WordPress.org 用户名；其他任何信息都将显示为不带个人资料链接和头像。 要更改某人的显示名称（该名称显示在插件的页面上），请编辑个人资料 https://wordpress.org/support/users/YOURID/edit/ 并更改显示名称。
  • Donate link – (可选) 在侧边栏中创建一个“向此插件捐赠”链接。 如果没有链接，则不会显示任何内容。
  • Tags – 1 到 5 个以逗号分隔的术语，用于描述插件。 插件不得使用竞争对手的插件名称作为标签。 插件不应使用仅适用于该插件的标签，因为这些标签将不会显示。
  • 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 文件的细节都很容易理解，但有一些部分可能会让用户感到困惑。

Readme 文件的解析方式

WordPress.org 的插件目录基于文件中 稳定版本字段中的信息进行工作。 当 WordPress.org 解析 readme.txt 文件时，它首先查看 /trunk 目录中的 readme.txt 文件，并读取“稳定版本”行。

当“稳定版本”设置正确时，WordPress.org 将在 /tags/ 目录中查找所引用的版本。 例如，如果“稳定版本”为“1.2.3”，则它将查找 /tags/1.2.3/ 目录。

位于标签文件夹中的 readme.txt 文件也必须正确更新，以包含正确的“稳定版本”；否则，您的插件可能无法更新。

如果“稳定版本”为 1.2.3，并且存在 /tags/1.2.3/ 目录，则系统不会再从 trunk 目录读取任何内容以供任何部分进行解析。 如果您尝试在 /trunk/readme.txt 文件中更改插件的描述，则这些更改将不会在您的插件页面上生效。 所有内容都来自指向“稳定版本”所指示的文件中的 readme.txt 文件。

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

“稳定版本”指向 /tags 目录中的一个子目录。 但是，插件的版本实际上不是由该文件夹名称决定的。 而是由插件的 PHP 文件本身中列出的版本来确定的。 如果您将“稳定版本”更改为 1.4，但插件仍然显示 1.3，则将显示的版本将为 1.3。

虽然使用 稳定版本设置为 trunk (而不是版本) 仍然可以在插件目录中工作，但这既不支持也不建议将其作为指示新版本的有效方法，并且已知会导致自动更新出现问题。 我们目前正在积极阻止使用“稳定版本：trunk”，并且禁止将其用于新的插件。

视频

您可以嵌入来自 YouTube、Vimeo 以及其他任何 WordPress 默认支持的平台的视频。 您只需将视频 URL 粘贴到 readme.txt 文件的单独行上即可。

我们建议您不要将视频放在 FAQ 节的最后一行，因为有时格式可能会出现问题。

Markdown

readme 文件使用 Markdown 的一个自定义版本。 大多数 Markdown 语法都按预期工作。

Markdown 允许您在 readme.txt 文件中轻松创建链接。 只需像这样编写即可：

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

您也可以将视频嵌入到 readme.txt 文件中。 位于单独行的 YouTube 或 Vimeo 链接将自动嵌入。 还可以使用 wpvideo 短代码嵌入 VideoPress 上的视频。

字段详情

对于那些想知道哪些信息会被解析成哪些信息的人：

  • Authors
    插件头文件中的“作者”字段和 readme 文件中的“贡献者”字段。
  • Version
    插件头文件中的“版本”字段。
  • Tags（如分类）
    readme 文件中的“标签”字段。
  • Plugin Name
    readme 文件中的插件名称，如果未提供，则使用插件头文件中的插件名称。
  • Author and Plugin Homepages
    插件头文件中的“作者 URI”和“插件 URI”字段。“插件 URI”应该是每个插件的唯一值。 不要将相同的 URI 用于您的免费插件和付费插件。 这样做会导致问题。
  • Last updated time
    在版本号更改后，在适当的目录中进行最后一次检查的时间。
  • Creation time
    首次检查的时间。

对于那些希望了解文件的详细信息，上述信息将提供参考。

文件大小

虽然 readme 文件是简单的文本文件，但如果文件大小超过 10k，可能会导致错误。 您的 readme 文件应该简明扼要。 描述不应是销售宣传，而应是对插件的功能和用途的描述。 安装说明应简洁明了。 FAQ 应该回答实际问题。

对于您的变更日志，我们建议将当前版本保存在 readme 文件中，并将其他版本信息放在单独的文件中，例如 changelog.txt 。 通过将所有较旧的变更日志数据存储在该文件中，您可以保持 readme 文件的简洁，并允许那些真正喜欢阅读详细变更日志的用户自行查看相关信息。

如果需要更详细的文档，其中包含内嵌图片等内容，请将用户引导至您的官方网站。

相关链接