WordPress как на ладони
Недорогой хостинг для сайтов на WordPress: wordpress.jino.ru Рекомендуемые продукты со скидкой от Template Monster

readme.txt

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

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

Для создания файла можно использовать плагин readme generator.

Для проверки корректности файла можно использовать валидатор readme.

Конвертер readme.txt в README.md (для GitHub) с нормальным Markdown.

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

=== Plugin Name ===
Contributors: Tkama
Donate link: http://example.com/
Tags: comments, spam
Requires at least: 3.0.1
Tested up to: 3.4
Requires PHP: 5.2.4
Stable tag: 4.3
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.

== 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 wp.org/wp-plugins.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*. Note that it might work on
higher versions... this is just the highest one you've verified.
*   Stable tag should indicate the Subversion "tag" of the latest stable version, or "trunk," if you use `/trunk/` for
stable.

	Note that the `readme.txt` of the stable tag is the one that is considered the defining one for the plugin, so
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.  In this situation, the only thing considered from the trunk `readme.txt`
is the stable tag pointer.  Thus, 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, it is assumed that trunk is stable, but you should specify "trunk" if that's where
you put the stable version, in order to eliminate any doubt.

== Installation ==

This section describes how to install the plugin and get it working.

e.g.

1. Upload `plugin-name.php` to the `/wp-content/plugins/` directory
1. Activate the plugin through the 'Plugins' menu in WordPress
1. Place `<?php do_action('plugin_name_hook'); ?>` in your templates

== 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). Note that the screenshot is taken from
the /assets directory or the directory that contains the stable readme.txt (tags or trunk). Screenshots in the /assets 
directory take precedence. For example, `/assets/screenshot-1.png` would win over `/tags/4.3/screenshot-1.png` 
(or jpg, jpeg, gif).
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.

== Arbitrary section ==

You may provide arbitrary sections, in the same format as the ones above.  This may be of use for extremely complicated
plugins where more information needs to be conveyed that doesn't fit into the categories of "description" or
"installation."  Arbitrary sections will be shown below the built-in sections outlined above.

== A brief Markdown Example ==

Ordered list:

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

Unordered list:

* something
* something else
* third thing

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 ?>`
меню

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

=== Plugin Name === (заголовки)

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

=== Plugin Name ===
Stable tag:        4.3
Tested up to:      3.4
Requires at least: 3.0.1
Requires PHP:      5.2.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.
Requires at least
Tested up to
Используются для проверки совместимости с ядром WordPress. Например, если указана требуемая версия 4.4, то пользователи версий ниже 4.4 не будут получать уведомления об обновлении. Поле Tested up to игнорирует минорные версии (в минорных версиях должны быть незначительные обновления). Это значит, что нужно указать только основную версию, с которой тестировался плагин. Указывать нужно только цифры: 4.9, а не WP 4.9.
WC Requires at least
WC Tested up to
Аналогичные поля для плагина WooCommerce. Когда создается плагин для плагина WC.
Requires PHP
Минимальная версия PHP на которой работает плагин.
Contributors
Это список (разделенный запятыми) имён людей с сайта WordPress.org (с учетом регистра), которые так или иначе работали над кодом плагина. Разработчики могут попросить удалить их из списка, потому что не хотят, чтобы плагин отображался на странице их профиля. Если использовать имя не с WordPress.org, то оно будет отображаться без ссылки на профиль и без gravatar. Если вы хотите изменить отображаемое имя (отображается на странице плагина), отредактируйте свой профиль https://wordpress.org/support/users/ВАШ_ID/edit/.
Tags
Теги (через запятую), которые соответствуют вашему плагину и его назначению. Теги важны, так как помогают найти плагин в репозитории (например для людей, которые любят просматривать по тегам). Также в теги можно включить название вашей компании, чтобы фильтровать плагины и, например, показать клиентам.
Donate link
Создает ссылку “Donate to this plugin” в сайдбаре каталога. Её можно не указывать.

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

меню

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

Если Stable Tag не указан, то он имеет значение по умолчанию trunk.

Stable Tag указывает на подкаталог в каталоге /tags, но версия плагина НЕ берется из названия этой папки. А берется из главного файла плагина. Так, например, если изменить Stable Tag на 1.4, а в PHP файле плагина по-прежнему указано 1.3, то версия будет 1.3.

Каталог 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 будет порядок.

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

4 коммента
  • mihdan421 www.kobzarev.com

    Не хватает еще конвертера readme.txt (wp.org) <-> README.md (GitHub)

    2
    Ответить8 мес назад #
  • @ Василий

    Поправьте, пожалуйста, опечатку:

    Теги (резе запятую), ...

    Ответить6 мес назад #
Здравствуйте, !     Войти . Зарегистрироваться