Plugin Readmes

セクションの詳細

すべてのプラグインにはメインのPHPファイルが含まれており、ほとんどすべてのプラグインにはreadme.txtファイルもあります。readme.txtファイルは、マークダウンのサブセットを使用して記述されることを意図しています。

ReadmeHeader情報

プラグインの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.

• 貢献者 – コードに貢献したすべてのWordPress.orgユーザー名のケースセンシティブなカンマ区切りリスト。フォークされたプロジェクトで作業した人々の名前を含めることは一般的に敬意を表することと見なされます。一部の開発者は、他のプラグインが自分のプロフィールページに表示されることを望まないため、リストから削除されることを求めることがあります。そのリクエストを尊重するのが最善です。WordPress.orgのユーザー名のみを使用することを忘れないでください。他のものはプロフィールリンクやグラバターなしで表示されます。プラグインのフロントページに表示される名前を変更するには、https://wordpress.org/support/users/YOURID/edit/のプロフィールを編集して表示名を変更します。
• 寄付リンク – (オプション) サイドバーに「このプラグインに寄付する」リンクを作成します。リンクがない場合、何も表示されません。
• タグ – プラグインを説明する1から5のカンマ区切りの用語。プラグインは競合プラグインの名前をタグとして使用することを控えるべきです。プラグインは、そのプラグインに固有のタグを使用すべきではありません。これらは表示されません。
• テスト済みバージョン – プラグインがテストされたWordPressのバージョン。このフィールドはマイナーバージョンを無視します。プラグインはマイナーアップデートで壊れるべきではありません。これは、プラグインがテストされたメジャーバージョンのみを定義する必要があり、WordPress.orgのプラグインディレクトリが自動的にマイナーバージョンを追加することを意味します。これは数字のみであるべきです。したがって、「4.9」とし、「WP 4.9」とはしないでください。
• PHPの必要条件 – (オプション) このプラグインを使用するために必要なPHPの最小バージョン。このフィールドも数字のみであるべきです。したがって、「7.0」とし、「PHP 7.0」とはしないでください。
• 安定版タグ – プラグインの安定版。これはWordPressのバージョンではなく、プラグイン自体のバージョンです。数字とピリオドのみを使用し、SemVerフォーマットが推奨されます。
• ライセンス – プラグインに使用されるGPLV2（またはそれ以降）互換ライセンス。
• ライセンスURI – (オプション) ライセンスへのリンク。これはオプションですが、プラグインがより珍しいライセンスを使用している場合は強く推奨されます。

ヘッダーセクションの最後には、プラグインの短い説明を記入する場所があります。例では150文字以内に収め、マークアップを使用しないことを推奨しています。そのテキスト行は、プラグイン名のすぐ下に表示されるプラグインの単一行説明です。150文字を超えると切り捨てられるため、短く保つようにしてください。

インストール

プラグインにカスタムインストール設定がない場合、このセクションを省略しても問題ありません。プラグインにカスタム構成ノートがある場合、インストール後にその情報を記載するのに最適な場所です。

カスタムセクション

カスタムセクションは許可されており、サポートされていますが、適度に使用してください。他のすべてのプラグインの見た目に慣れている人々が、あなたのプラグインが奇妙な場合、重要な情報を見逃すことがあります。

技術的詳細

ほとんどのreadmeの詳細は自明ですが、いくつかのセクションは人々を混乱させることがあります。

Readmeの解析方法

現在、トランクの安定版タグを使用することはプラグインディレクトリで機能しますが、新しいバージョンを示すためのサポートされていないまたは推奨されない方法であり、自動更新に問題を引き起こすことが知られています。現在、私たちはその使用を積極的に控えるようにしており（新しいプラグインの場合は使用を禁止しています）。

WordPress.orgのプラグインディレクトリは、readmeの安定版タグフィールドに見つかった情報に基づいて動作します。WordPress.orgがreadme.txtを解析すると、最初に行うことはreadme.txtを/trunkディレクトリで見て、「安定版タグ」行を読み取ることです。

安定版タグが正しく設定されている場合、WordPress.orgは/tags/で参照されたバージョンを探しに行きます。したがって、安定版タグが「1.2.3」の場合、/tags/1.2.3/を探します。

タグフォルダ内のreadme.txtも正しく更新されて、正しい「安定版タグ」を持っている必要があります。これを怠ると、プラグインが更新できなくなる可能性があります。

安定版タグが1.2.3で/tags/1.2.3/が存在する場合、トランク内の他の部分はシステムによって解析されることはありません。/trunk/readme.txtでプラグインの説明を変更しようとすると、変更はプラグインページに何も反映されません。すべては安定版タグによって指し示されたファイル内のreadme.txtから来ます。

WordPress.orgのプラグインディレクトリは、プラグインのメインPHPファイルを読み取って、プラグインの名前、プラグインURI、そして最も重要なバージョン番号を取得します。プラグインページでは、「バージョン1.2.3をダウンロード」と表示されるダウンロードボタンが見えます。そのバージョン番号はプラグインのメインPHPファイルから来ており、readmeからではありません！

安定版タグは/tagsディレクトリ内のサブディレクトリを指します。しかし、プラグインのバージョンは実際にはそのフォルダ名によって設定されるわけではありません。代わりに、プラグインのPHPファイル自体に記載されているバージョンが名前を決定します。安定版タグを1.4に変更し、プラグインがPHPファイル内で1.3と表示されている場合、表示されるバージョンは1.3になります。

ビデオ

YouTube、Vimeo、その他の場所からビデオを埋め込むことができますWordPressがデフォルトでサポートしている。ビデオURLをreadmeの独自の行に貼り付けるだけです。

FAQセクションの最後の行にビデオを配置しないことをお勧めします。時々フォーマットが奇妙になることがあります。

マークダウン

readmeはカスタマイズされたバージョンのMarkdownを使用しています。ほとんどのMarkdown呼び出しは期待通りに機能します。

Markdownを使用すると、readme.txt内で簡単にリンクを作成できます。単語をURLにリンクするには、次のように書きます:

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

ビデオもreadme.txtに入れることができます。YouTubeまたはVimeoのリンクを独自の行に置くと、自動的に埋め込まれます。また、wpvideoショートコードを使用してVideoPressにホストされたビデオを埋め込むことも可能です。

フィールドの詳細

何が何に解析されるか正確に知りたい人のために:

• 著者
  プラグインヘッダーの著者フィールドとreadmeファイルの貢献者フィールド。
• バージョン
  プラグインヘッダーのバージョンフィールド。
• タグ（カテゴリとして）
  readmeファイルのタグフィールド。
• プラグイン名
  readmeファイルのプラグイン名がプラグインヘッダーで指定されたプラグイン名にフォールバックします。
• 著者とプラグインのホームページ
  プラグインヘッダーの著者URIとプラグインURIフィールド。プラグインURIは各プラグインに固有であるべきです。無料プラグインとプロプラグインに同じURIを使用しないでください。悪い結果になります。
• 最終更新時刻
  バージョン番号変更後の適切なディレクトリへの最終チェックインの時間。
• 作成時刻
  最初のチェックインの時間。
  

ファイルサイズ

readmeは単純なテキストファイルですが、10kを超えるファイルサイズはエラーを引き起こす可能性があります。readmeは簡潔で要点を押さえたものであるべきです。説明はプラグインの説明、機能、使用方法の説明であり、販売の提案ではないべきです。インストール手順は直接的であるべきです。FAQは実際の問題に対処するべきです。

変更ログについては、現在のリリースをreadmeに保持し、残りを独自のファイルに分割することをお勧めします — 例えばchangelog.txt。すべての古い変更ログデータをそこに保存することで、readmeを小さく保ち、長い変更ログに本当に興味がある人々が自分で読むことを可能にします。

同様に、インライン画像などを含む詳細なドキュメントが必要な場合は、自分のウェブサイトに人々を誘導してください。

関連情報

• プラグインヘッダー（プラグインのメインファイルに見つかる）