readme.txt

Все плагины WordPress содержат основной PHP файл. А файлы из каталога WP, также содержат обязательный файл readme.txt. В этом файле размещается информация о плагине для каталога WordPress. Так например, 90% информации на странице плагина в каталоге WordPress берется из readme.txt.

Иногда этот файл может использоваться и другими парсерами, плагинами и т.д. Поэтому можно сказать, что это важный файл плагина, если вы делаете публичный плагин. И даже если вы не размещаете плагин в каталоге WordPress все равно будет не лишним создать такой файл в вашем плагине.

Пример файла readme.txt

https://wordpress.org/plugins/readme.txt

GitHub

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

== Description ==

This is the long description.  No limit, and you can use Markdown (as well as in the following sections).

For backwards compatibility, if this section is missing, the full length of the short description will be used, and
Markdown parsed.

A few notes about the sections above:

* "Contributors" is a comma separated list of wordpress.org usernames
* "Tags" is a comma separated list of tags that apply to the plugin
* "Requires at least" is the lowest version that the plugin will work on
* "Tested up to" is the highest version that you've *successfully used to test the plugin*
* Stable tag must indicate the Subversion "tag" of the latest stable version

Note that the `readme.txt` value of stable tag is the one that is the defining one for the plugin.  If the `/trunk/readme.txt` file says that the stable tag is `4.3`, then it is `/tags/4.3/readme.txt` that'll be used for displaying information about the plugin.

If you develop in trunk, you can update the trunk `readme.txt` to reflect changes in your in-development version, without having that information incorrectly disclosed about the current stable version that lacks those changes -- as long as the trunk's `readme.txt` points to the correct stable tag.

If no stable tag is provided, your users may not get the correct version of your code.

== Frequently Asked Questions ==

= A question that someone might have =

An answer to that question.

= What about foo bar? =

Answer to foo bar dilemma.

== Screenshots ==

1. This screen shot description corresponds to screenshot-1.(png|jpg|jpeg|gif). Screenshots are stored in the /assets directory.
2. This is the second screen shot

== Changelog ==

= 1.0 =
* A change since the previous version.
* Another change.

= 0.5 =
* List versions from most recent at top to oldest at bottom.

== Upgrade Notice ==

= 1.0 =
Upgrade notices describe the reason a user should upgrade.  No more than 300 characters.

= 0.5 =
This version fixes a security related bug.  Upgrade immediately.

== A brief Markdown Example ==

Markdown is what the parser uses to process much of the readme file.

[markdown syntax]: https://daringfireball.net/projects/markdown/syntax

Ordered list:

1. Some feature
1. Another feature
1. Something else about the plugin

Unordered list:

* something
* something else
* third thing

Links require brackets and parenthesis:

Here's a link to [WordPress](https://wordpress.org/ "Your favorite software") and one to [Markdown's Syntax Documentation][markdown syntax]. Link titles are optional, naturally.

Blockquotes are email style:

> Asterisks for *emphasis*. Double it up  for **strong**.

And Backticks for code:

`<?php code(); ?>`

Секции (разделы) readme.txt

=== Plugin Name ===

Заголовки readme.txt состоят из следующих данных:

=== Plugin Name ===
Stable tag:        4.3
Tested up to:      3.4
Contributors:      (this should be a list of wordpress.org userid's)
Donate link:       http://example.com/
Tags:              comments, spam
License:           GPLv2 or later
License URI:       http://www.gnu.org/licenses/gpl-2.0.html
WC requires at least: 3.0
WC tested up to:      3.5

Here is a short description of the plugin. This should be no more than 150 characters. No markup here.

Plugin Name

Название плагина. Меняем на название своего плагина.

Stable tag

Стабильная версия плагина – последняя доступная версия, которую вы считаете стабильной. Это очень важный тег, поскольку он определяет, какая версия плагина будет скачиваться с репозитория. Подробнее см. ниже в разделе Как парсится readme.

Tested up to

С какой максимальной версией WP был протестирован плагин. Нужно указать только мажорные версии. Указывать нужно только цифры: 4.9, а не WP 4.9.

Requires PHP(OPTIONAL)

Требуемая минимальная версия PHP, необходимая для использования этого плагина. Здесь должны быть только цифры: 7.0, а не PHP 7.0.

WC Requires at least

WC Tested up to

Аналогичные поля для плагина WooCommerce. Когда создается плагин для плагина WC.

Contributors

Это список (разделенный запятыми) имён людей с сайта WordPress.org (с учетом регистра), которые так или иначе работали над кодом плагина. Разработчики могут попросить удалить их из списка, потому что не хотят, чтобы плагин отображался на странице их профиля. Если использовать имя не с WordPress.org, то оно будет отображаться без ссылки на профиль и без gravatar. Если вы хотите изменить отображаемое имя (отображается на странице плагина), отредактируйте свой профиль https://wordpress.org/support/users/ВАШ_ID/edit/.

Tags

Теги (через запятую), которые соответствуют вашему плагину и его назначению. Теги важны, так как помогают найти плагин в репозитории (например для людей, которые любят просматривать по тегам). Также в теги можно включить название вашей компании, чтобы фильтровать плагины и, например, показать клиентам.

Donate link

Создает ссылку “Donate to this plugin” в сайдбаре каталога. Её можно не указывать.

В конце находится место для короткого описания плагина. Рекомендуется не более 150 символов и не использовать разметку. Эта строка текста представляет собой однострочное описание плагина, которое отображается прямо под именем плагина. Если он длиннее 150 символов, он обрезается, поэтому держите его коротким.

Requires at least (не работает с версии WP 5.8)

Используются для проверки совместимости с ядром WordPress. Например, если указана требуемая версия 4.4, то пользователи версий ниже 4.4 не будут получать уведомления об обновлении.

== Description ==

Подробное описание плагина (можно использовать Markdown, см. ниже).

== Frequently Asked Questions ==

В этом разделе создается список часто задаваемых вопросов.

Список создается в таком формате:

= Заголовок вопроса 1 =
Ответ на вопрос 1.

= Заголовок вопроса 2 =
Ответ на вопрос 2.

== Installation ==

Этот раздел обычно создается, когда установка плагина требует каких-либо дополнительных действий. Если плагин устанавливается и не требует никаких доп настроек, то этот раздел можно опустить.

== Screenshots ==

Скриншоты плагина. В формате:

1. Описание скриншота один
2. Описание скриншота два

Файлы скриншотов должны располагаться в каталоге WP, в общей папке /assets или в корневой папке стабильной версии плагина. Название файла будет такое: screenshot-ЧИСЛО.png|jpg|jpeg|gif. Например: screenshot-1.jpg и sreenshot-2.png.

Файлы в главной папке /assets имеют больший приоритет. Например, /assets/screenshot-1.png выиграет у /tags/4.3/screenshot-1.(png|jpg|jpeg|gif).

Описание элементов списка станет подписью к картинке. В описании можно использовать URL, если нужно.

== Upgrade Notice ==

Важные заметки обновлениям. Лог обновлений ведется в разделе changelog, а в этом разделе рекомендуется вписывать очень важные заметки, например, когда были внесенны несовместимые с прошлой версией изменения или когда после обновления нужно что-либо сделать чтобы плагин продолжал работать как нужно.

Рекомендуемый формат:

= 1.3 =
В версии 1.3 была запрещена функция `foo()`, заменить её на `bar()` в своих проектах.

= 1.0 =
Изменилось название таблицы плагина с `wp_foo` на `wp_myplug`.

Этот раздел не виден на главной странице репозитория. Это содержание будет видно в админке WordPress (при клике на ссылку "Детали" на странице wp-admin/plugins.php или wp-admin/update-core.php.

== Changelog ==

Список изменения, рекомендуется в формате списка:

= 1.0 =
* A change since the previous version.
* Another change.

= 0.5 =
* List versions from most recent at top to oldest at bottom.

== Произвольная секция ==

В readme можно указывать любые секции. Не рекомендуется создавать много секций. В идеале нужно ограничится базовыми секциями, чтобы сохранялся привычный стандарт описания плагина.

Примеры произвольных секций:

== Translations ==

* English - default, always included
* German: Deutsch - immer dabei!

*Note:* All my plugins are localized/ translateable by default. For translating I recommend the awesome plugin [Code Localization](http://site.org/code-localization/).

== Additional Info ==
**Idea Behind / Philosophy:** Just a little leightweight plugin...

== Credits ==
* Thanks to [Dominik Schilling](http://wpgrafie.de/) [@ocean90](http://twitter.com/#!/ocean90) for great help with the CSS for the first level icon in WordPress 3.3!

Как парсится readme

Каталог плагинов WordPress.org работает на основе информации, найденной в поле Stable Tag, в файле readme.txt. WordPress.org считывает readme.txt в директории /trunk (в каталоге плагинов), читается значение поля Stable Tag. Когда Stable Tag отсутствует или равен trunk, стабильной версией плагина считается код в папке /trunk. Если для Stable Tag задана конкретная версия, то эта версия будет проверяться (должна находится) в каталоге /tags/. Например, если указана версия 1.2.3, то все данные плагина будут взяты из папки /tags/1.2.3/. Тут возможно 2 сценария:

• /tags/1.2.3/ существует — /trunk не будет использован при анализе чего угодно. Так, например, если попытаться изменить описание плагина в /trunk/readme.txt, но Stable Tag не равно trunk, то внесенные изменения ничего не изменят на странице плагина, потому что данные будут взяты из readme.txt, на который указывает Stable Tag.

• /tags/1.2.3/ НЕ существует — для анализа будет использована папка /trunk.

Каталог WordPress.org читает основной PHP файл плагина, чтобы получить: имя плагина, URI плагина, номер версии. В кнопке загрузки на странице плагина используется версия указанная в основном файле плагина (не из readme)!

Markdown

В readme используется немного измененная версия Markdown. 90% синтаксиса Markdown работает как ожидается.

Можно использовать Markdown ссылки. У них стандартный синтаксис:

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

Пример Markdown маркировки для других элементов:

Нумерованный список:

1. Some feature
1. Another feature
1. Something else about the plugin

Ненумерованный список:

* something
* something else
* third thing

Ненумерованный список (многоуровневый):

* First item
* Second item
  * Tird item (2 уровень)
  * Fouth item (2 уровень)
* Fifth item (1 уровень)
* etc.

Here's a link to [WordPress](https://wordpress.org/ "Your favorite software") and one to [Markdown's Syntax Documentation][markdown syntax].
Titles are optional, naturally.

[markdown syntax]: http://daringfireball.net/projects/markdown/syntax
			"Markdown is what the parser uses to process much of the readme file"

Markdown uses email style notation for blockquotes and I've been told:
> Asterisks for *emphasis*. Double it up  for **strong**.

`<?php code(); // goes in backticks ?>`

Видео

Можно встраивать видео из YouTube, Vimeo и других сервисов из белого списка WordPress.

Вставляется видео как ссылка на видео на отдельной строке в readme файле.

Не рекомендуется добавлять ссылку последней строкой файла, потому что иногда форматирование может сломаться и ссылка не преобразуется в код видео.

Размер файла

Файл размером более 10k может привести к ошибкам. readme по возможности должен быть кратким. Не нужно совать в readme все что угодно, используйте ссылки, например ссылки на описание плагина на вашем сайте.

Большой список изменений, можно вынести в отдельный файл, например, changelog.txt а в readme указать ссылку на этот файл. Так в readme будет порядок.

Полезные ссылки

• Офф дока: https://developer.wordpress.org/plugins/wordpress-org/how-your-readme-txt-works/
• Проверка и просмотр readme (инструмент): https://wpreadme.com/
• Конвертор readme в markdown (GitHub): https://github.com/wpreadme2markdown/wp-readme-to-markdown
• Форматирование readme (англ)