次の方法で共有

NuGet.org のパッケージのReadmeファイル

NuGet パッケージに readme ファイルを含めて、 パッケージの詳細をより充実させ、ユーザーにとってより有益なものにします。

これは、ユーザーが NuGet.org でパッケージの詳細ページを表示したときに表示される最初の要素の 1 つであり、良い印象を与えるために不可欠です。

Von Bedeutung

NuGet.org では、 Markdown の readme ファイルと、限られたドメイン のセットからのイメージのみがサポートされます。 NuGet.org で readme が正しくレンダリングされるように、イメージとサポートされている Markdown 機能に対して許可されているドメインを参照してください。

readme には何を含める必要がありますか?

readme に次の項目を含めてみてください。

  • パッケージの概要と実行内容 - どのような問題が解決されますか?
  • パッケージの使用を開始する方法 - 特定の要件はありますか?
  • readme 自体に含まれていない場合は、より包括的なドキュメントへのリンク。
  • 少なくともいくつかのコード スニペットおよび例の画像。
  • プロジェクトの問題、Twitter、バグ トラッカー、その他のプラットフォームへのリンクなどのフィードバックを残す場所と方法。
  • 投稿する方法 (該当する場合)。

たとえば、次のパッケージ README テンプレートから始めることができます。

# Package readme title, e.g., display name or title of the package (optional)

Start with a clear and concise description: A brief overview of what your package is and does, also what problem it solves.

## Getting started

Explain how to use your package, provide clear and concise getting started instructions, including any necessary steps.

### Prerequisites

What are specific minimum requirements to use your packages? Consider excluding this section if your package works without any additional setup beyond simple package installation.

## Usage

Examples about how to use your package by providing code snippets/example images, or samples links on GitHub if applicable. 

- Provide sample code using code snippets
- Include screenshots, diagrams, or other visual help users better understand how to use your package

## Additional documentation

Provide links to more resources: List links such as detailed documentation, tutorial videos, blog posts, or any other relevant documentation to help users get the most out of your package.

## Feedback

Where and how users can leave feedback?

- Links to a GitHub repository where could open issues, Twitter, a Discord channel, bug tracker, or other platforms where a package consumer can connect with the package author.

高品質の readmes は、さまざまな形式、形状、サイズで提供される可能性があることに注意してください。 NuGet.org でパッケージを既に使用できる場合は、リポジトリに既に readme.md またはその他のドキュメント ファイルがあり、NuGet.org の詳細ページに大きく追加されている可能性があります。

注

いくつかのベスト プラクティスについては 、高品質の 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 readmes は、Markdig 解析エンジンを介して CommonMark 準拠 の Markdown をサポートします。

NuGet.org は現在、次の Markdown 機能をサポートしています。

構文の強調表示もサポートしています。言語識別子を追加して、コードスパンで構文の強調表示を有効にすることができます。