readme.txt

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

Іноді цей файл можна використовувати й іншими парсерами, плагінами тощо. Тому можна сказати, що це важливий файл плагіна, якщо ви робите публічний плагін. І навіть якщо ви не розміщуєте плагін у каталозі WordPress, все одно буде не зайвим створити такий файл у вашому плагіні.

Приклад файлу readme.txt

=== Plugin Name ===
Contributors: Tkama
Donate link: http://example.com/
Tags: коментарі, spam
Tested up to: 3.4
Stable tag: 4.3
Ліцензія: 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

Тут є короткий опис Plug-in. Це повинно бути більше 150 characters. No markup here.

== Description ==

Це є тривалий опис. Чи не обмежений, і ви можете використовувати Markdown (як добре, як в наступних секціях).

Для backwards compatibility, якщо ця секція є помітною, повною частиною короткого опису буде використовуватися, і
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
* "Тестований вгору" є високою версією, що ви *успішно використовували для перевірки plugin*. Note that it might work on
higher versions... this is just the highest one you've verified.
* Стабільний tag повинен визначати Subversion "tag" з останньою стабільною версією, або "trunk," if you use `/trunk/` for
стабільний.

	Зверніть увагу на те, що 'readme.txt' значний 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
для відтворення інформації про plugin. У цьому положенні, тільки це розглядається з trunk `readme.txt`
is the stable tag pointer. Це, якщо ви розробляєте в клунку, ви можете update trunk `readme.txt` до reflect changes in
Ваша розробка версії без будь-якої інформації, що правильно розповсюджується про поточну версію версії
що лаки цих змін - як довгий як trunk's `readme.txt` points to the correct stable tag.

	Якщо не встановлений tag є забезпеченим, він є впевнений, що trunk є стійким, але ви повинні особливість "trunk" if that's where
ви збираєтеся на стару версію, в порядку до eliminate any doubt.

== Installation ==

Ця секція описується, як додати до plugin and get it working.

eg

1. Upload `plugin-name.php` до `/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. Цей штриховий шрифт описаний на екрані-1.(png|jpg|jpeg|gif). Note that the screenshot is taken from
/assets directory або directory that contains the stable readme.txt (tags or trunk). Screenshots in the /assets
directory таке precedence. Для прикладу, `/assets/screenshot-1.png` would win over `/tags/4.3/screenshot-1.png`
(або jpg, jpeg, gif).
2. This is the second screen shot

== Changelog ==

= 1.0 =
* A зміна since the previous version.
* Another change.

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

== Upgrade Notice ==

= 1.0 =
Upgrade notices describe the reason a user should upgrade. No більше 300 characters.

= 0.5 =
Це version fixes a security related bug. Upgrade immediately.

== Arbitrary section ==

Ви можете зробити arbitrary sections, в тому ж форматі, як ones above. Цей може бути використаний для надзвичайно складних
plugins where more information необхідні для того, щоб переконатися, що не fit в категорії "подання" або
"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

Натисніть на [WordPress](https://wordpress.org/ "Вибраний програмний продукт") і один до [Markdown's Syntax Documentation][markdown syntax].
Titles є optional, naturally.

[markdown syntax]: http://daringfireball.net/projects/markdown/syntax
			"Markdown is what the parser uses to process велику з the readme file"

Markdown за допомогою 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
Contributors: (Цей повинен бути лист з wordpress.org userid's)
Donate link: http://example.com/
Tags: коментарі, spam
Ліцензія: 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

Тут є короткий опис Plug-in. Це повинно бути більше 150 characters. No markup here.

Plugin Name

Назва плагіна. Змінюємо назву свого плагіна.

Stable tag

Стабільна версія плагіна – остання доступна версія, яку ви вважаєте стабільною. Це дуже важливий тег, оскільки він визначає, яка версія плагіна скачуватиметься з репозиторію. Докладніше див. нижче в розділі
Як парситься readme .

Requires at least (не працює з WP 5.8)

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

Tested up to

З якою максимальною версією WP було протестовано плагін. Потрібно вказати лише мажорні версії. Вказувати потрібно лише цифри:
4.9, а чи не
WP 4.9.

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 символів, він обрізається, тому тримайте його коротким.

== 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 зміна since the previous version.
* Another change.

= 0.5 =
* List versions з 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. Для перетворення I recommend 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) для великої Help with CSS для першого рівня icon в 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/. Тут можливо два сценарії:

• /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.

Натисніть на [WordPress](https://wordpress.org/ "Вибраний програмний продукт") і один до [Markdown's Syntax Documentation][markdown syntax].
Titles є optional, naturally.

[markdown syntax]: http://daringfireball.net/projects/markdown/syntax
			"Markdown is what the parser uses to process велику з the readme file"

Markdown за допомогою 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 буде порядок.

Корисні посилання

• Перевірка та перегляд readme (інструмент)
• Форматування readme (англ)
• Конвертор readme в markdown (GitHub)