このページでは、プラグイン・ディレクトリのいくつかの側面を説明し、多くの人々が見逃している、より明白な側面について説明します。
プラグイン・ブラウザのエントリーを最も有用なものにするために、各プラグインは、WordPress プラグイン readme ファイル標準に準拠した readme.txt という名称の readme ファイルを持つ必要があります。このファイルは、ディレクトリのフロントページの出力を制御します。readme に詳細を記述することで、wordpress.org/plugins/Your-Plugin に何が表示されるかが決まります。
プラグイン readme ジェネレーターを使い完成した結果を、公式 readme バリデーターを通してチェックできます。より視覚的な支援が必要な場合は、wpreadme.comというツールを使うことができます。
WordPress 5.8以降、プラグインの readme ファイルは、要件としてパースされることはありません。これは、ヘッダー Requires PHP と Requires at least が、プラグインのメイン PHP ファイルからパースされることを意味します。
セクション詳細
すべてのプラグインにはメインの PHP ファイルがあり、ほぼすべてのプラグインにはファイル readme.txt もあります。ファイル readme.txt は、Markdown のサブセットを使って記述することを想定しています。
Readme ヘッダー情報
プラグインの readme ヘッダーは、この情報で構成されています:
=== 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～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文字以内で、マークアップを使わないことを推奨しています。そのテキスト行は、プラグイン名のすぐ下に表示される、プラグインの1行説明です。150文字より長いとカットされてしまうので、短く書きましょう。
導入方法
プラグインにカスタム・インストール設定がない場合、このセクションは省略してもかまいません。もしあなたのプラグインにインストール後のカスタム設定メモがある場合、ここはその情報を書くのに最適な場所です。
カスタム・セクション
カスタム・セクションは許可され、サポートされていますが、節度を持って使用してください。他のプラグインの見た目に慣れてしまうと、あなたのプラグインが変わっていると、重要な情報を見逃してしまいます。
技術的な詳細
Readme の詳細のほとんどは自明ですが、つまづく可能性のある箇所がいくつかあります。
Readme のパース方法
WordPress.org のプラグイン・ディレクトリは、readme の Stable Tag フィールドにある情報にもとづいて動作します。WordPress.org が readme.txt をパースする際、最初に行うのはディレクトリ /trunk の readme.txt を見ることで、そこで「Stable Tag」行を読み取ります。
Stable Tag が適切に設定されると、WordPress.org は /tags/ で参照されているバージョンを検索します。つまり、「1.2.3」の Stable Tag は /tags/1.2.3/ を検索することになります。
もし Stable Tag が1.2.3であり、/tags/1.2.3/ が存在するなら、trunk に含まれるものは、システムのどの部分からもパースされるために、それ以上読み込まれることはありません。/trunk/readme.txt でプラグインの説明を変更しようとする場合、その変更はプラグインページでは何も意味を持ちません。すべては、Stable Tag が指し示しているファイルの readme.txt から由来します。
WordPress.org のプラグイン・ディレクトリは、プラグインの PHP ファイルを読み込み、プラグインの名前、プラグイン URI、そして最も重要なバージョン番号などを取得します。プラグインページには、「バージョン1.2.3をダウンロード」などと書かれたダウンロードボタンがあります。そのバージョン番号は、プラグインのメイン PHP ファイルから取得したもので、readme から取得したもの ではありません !
Stable Tag は、ディレクトリ /tags のサブディレクトリを指し示します。しかし、プラグインのバージョンは、実際にはそのフォルダー名では設定されません。その代わりに、プラグインの PHP ファイル自体に記載されているバージョンによって、名前が決まります。Stable Tag を1.4に変更しても、プラグインの PHP ファイルに1.3と記載されている場合、バージョンは1.3となります。
動画
YouTube、Vimeo、その他WordPress がデフォルトでサポートしているどこからでも、動画を埋め込むことができます。動画の URL を、readme の専用行に貼り付けるだけです。
フォーマットが変になることがあるので、動画を FAQ セクションの最終行に「しない」ことをおすすめします。
Markdown
readme は、Markdown のカスタマイズ版を使用しています。ほとんどの Markdown 呼び出しは、期待通りに動作します。
Markdown を使えば、readme.txt にも簡単にリンクを張ることができます。単語を URL にリンクさせるには、このように書くだけです:
[WordPress](http://wordpress.org)
動画も readme.txt に入れることができます。YouTube や Vimeo のリンクを1行に記述すると、自動的に埋め込まれます。wpvideo ショートコードを使用して、VideoPress でホストされている動画を埋め込むことも可能です。
フィールド詳細
何が何にパースされるのかを、正確に知りたい人のために:
- Authors
プラグイン・ヘッダーの Author フィールドと readme ファイルの Contributors フィールド。 - Version
プラグイン・ヘッダーの Version フィールド。 - Tags (カテゴリーと同じ)
readme ファイルの Tags フィールド。 - Plugin Name
readme ファイルの Plugin Name は、プラグイン・ヘッダーで指定された Plugin Name にフォールバックする。 - Author and Plugin Homepages
プラグイン・ヘッダーの Author URI と Plugin URI フィールド。プラグイン URI は、各プラグインに対して 一意 でなければなりません。無償プラグインとプロプラグインに同じ URI を使用 しないでください。酷い結果になります。 - Last updated time
バージョン番号変更後、該当ディレクトリにチェックインした最後の時刻。 - Creation time
初回 チェックインの時刻。
ファイル・サイズ
readme は、シンプルなテキストファイルですが、10k を超えるファイルはエラーになる可能性があります。readme は、簡潔で要点を押さえたものでなければなりません。説明文は、売り込みではなく、プラグインの説明、プラグインが何をするのか、プラグインの使い方を説明してください。インストール手順は、直接的であるべきです。FAQ は、実際に課題に対処したものであるべきです。
変更履歴については、現在のリリースを readme に残し、残りを独自のファイル — たとえば、changelog.txt — に分割することをおすすめします。古い変更履歴のデータをすべてそこに保存することで、readme を小さく保つことができ、長い変更履歴を読みたがる人は、自分で読めます。
同様に、インライン画像などを含む詳細な文書が必要な場合は、人々を独自の web サイトに誘導しましょう。
関連記事
- プラグイン・ヘッダー (プラグインのメイン・ファイルにあります)