NuGet.org でのパッケージの readme
NuGet パッケージに readme ファイルを含めることにより、パッケージの詳細を充実させ、ユーザーにとって有益なものにすることができます。
これは、おそらく、ユーザーが NuGet.org でパッケージの詳細ページを表示して最初の見る要素の 1 つであり、良い印象を与えるために不可欠です。
重要
NuGet.org でサポートされているのは、Markdown での readme ファイルと、限られたドメインのセットの画像のみです。 NuGet.org で readme が正しく表示されるように、画像で許可されているドメインとサポートされている Markdown 機能を確認してください。
readme に含める必要があるもの
readme には次の項目を含めることを検討してください。
- パッケージの概要と動作についての説明 - どのような問題が解決されるか?
- パッケージの使用を開始する方法 - 特定の要件があるか?
- readme 自体に含まれていない場合に、より包括的なドキュメントへのリンク。
- 少なくともいくつかのコード スニペットやサンプルまたは画像の例。
- フィードバックを行う場所と方法。プロジェクトの問題、Twitter、バグ トラッカー、または他のプラットフォームへのリンクなど。
- 投稿方法 (該当する場合)。
高品質の readme は、さまざまな形式、形状、サイズで提供されることに注意してください。 NuGet.org で使用可能なパッケージが既にある場合は、リポジトリに readme.md や他のドキュメント ファイルが既に存在し、それが NuGet.org の詳細ページに追加するのに適している可能性があります。
Note
いくつかのベスト プラクティスについては、高品質の README の作成に関するブログを参照してください。
readme をプレビューする
NuGet.org で公開される前に readme ファイルをプレビューするには、NuGet.org のパッケージのアップロード Web ポータルを使用してパッケージをアップロードし、メタデータ プレビューの [Readme File]\(readme ファイル\) セクションまで下にスクロールします。 次のように見えるはずです。
時間をかけて、画像のコンプライアンスとサポートされている書式設定について readme ファイルを繰り返しプレビューし、潜在的なユーザーに優れた印象を与えられることを確認することを検討してください。 NuGet.org に公開した後でパッケージの readme の誤りを修正するには、修正プログラムを使用して、更新されたパッケージのバージョンをプッシュする必要があります。 すべてに問題がないことを事前に確認することで、将来の頭痛の種を取り除くことができます。
画像とバッジに許可されているドメイン
セキュリティとプライバシーの問題により、NuGet.org では、画像やバッジをレンダリングできるドメインが、信頼されたホストに制限されています。
NuGet.org によりレンダリングが許可されているのは、次の信頼されたドメインのバッジを含むすべての画像です。
- api.codacy.com
- app.codacy.com
- api.codeclimate.com
- api.dependabot.com
- api.travis-ci.com
- api.reuse.software
- app.fossa.com
- app.fossa.io
- avatars.githubusercontent.com
- badge.fury.io
- badgen.net
- badges.gitter.im
- buildstats.info
- caniuse.bitsofco.de
- camo.githubusercontent.com
- cdn.jsdelivr.net
- cdn.syncfusion.com
- ci.appveyor.com
- circleci.com
- codecov.io
- codefactor.io
- coveralls.io
- dev.azure.com
- flat.badgen.net
- github.com/.../workflows/.../badge.svg
- gitlab.com
- img.shields.io
- i.imgur.com
- isitmaintained.com
- opencollective.com
- raw.github.com
- raw.githubusercontent.com
- snyk.io
- sonarcloud.io
- travis-ci.com
- travis-ci.org
- wakatime.com
- user-images.githubusercontent.com
別のドメインを許可リストに追加する必要があると思われる場合は、遠慮なく問題を提出してください。エンジニアリング チームによって、プライバシーとセキュリティのコンプライアンスに関するレビューが行われます。 相対ローカル パスで指定された画像と、サポートされていないドメインからホストされている画像はレンダリングされず、パッケージ所有者にのみ表示される readme ファイルのプレビューとパッケージ詳細ページで警告が発生します。
サポートされている Markdown 機能
Markdown は、プレーン テキスト形式の構文を使用する軽量のマークアップ言語です。 NuGet.org の readme では、Markdig 解析エンジンによる CommonMark 準拠の Markdown がサポートされています。
現在、NuGet.org によってサポートされている Markdown の機能は次のとおりです。
構文の強調表示もサポートしています。言語識別子を追加して、コード範囲で構文の強調表示を有効にすることができます。