通过

NuGet.org 上的包说明文件

在 NuGet 包中包含自述文件，这样可以使包详细信息更加丰富，并且更具信息性！

这可能是用户在 NuGet.org 上查看程序包详细信息页面时会看到的第一个元素之一，对于给人留下良好印象至关重要！

重要

NuGet.org 仅支持 Markdown 中的自述文件以及来自一组有限域的图像。 查看 允许的图像域 和 支持的 Markdown 功能，以确保您的自述文件在 NuGet.org 上正确呈现。

我的自述文件应包括哪些内容？

请考虑在文件中包括以下信息：

  • 有关您的软件包是什么及其功能的介绍——它解决了哪些问题？
  • 如何开始使用程序包 - 是否有任何特定要求？
  • 如果自述文件本身未包含，则提供到更全面文档的链接。
  • 至少几个代码片段/示例或示例图像。
  • 如何以及在哪里留下反馈，例如项目问题页面、Twitter、bug 跟踪器或其他平台的链接。
  • 如何参与（如果适用）。

例如，您可以从此包的 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.

请记住，高质量的README文件可以有丰富多样的格式和形式！ 如果你已经在 NuGet.org 上有一个可用的包，很可能在你的存储库中已有一个 readme.md 或其他文档文件，这将是对你 NuGet.org 详细信息页的极好补充。

注释

阅读我们的 博客，了解编写高质量自述文件的一些最佳做法。

预览README文件

若要在 NuGet.org 上实时预览自述文件之前，请在 NuGet.org 上使用“上传包”Web 门户 上传包，然后向下滚动到元数据预览的“自述文件”部分。 结果应如下所示：

说明文件预览

请考虑花时间查看和预览自述文件，了解图像符合性和受支持的格式，以确保它给潜在用户带来良好的第一印象！ 为了在包自述文件发布到 NuGet.org 后更正错误，您需要上传一个包含修复的更新包版本。 确保一切准备就绪可以避免日后的麻烦。

图像和徽章的允许域名

由于安全和隐私问题，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

如果你认为另一个域应该添加到允许列表中，请随意 提出问题 ，我们的工程团队将审查其隐私和安全合规性。 使用相对本地路径的图像和托管在不受支持域中的图像将不会被呈现，并且会在自述文件预览和包详细信息页面上生成警告，只有包所有者可以看到这些警告。

支持的 Markdown 功能

Markdown 是一种轻型标记语言，采用纯文本格式语法。 NuGet.org 自述通过 Markdig 分析引擎支持符合 CommonMark 标准的 Markdown。

NuGet.org 目前支持以下 Markdown 功能：

我们还支持语法突出显示，可以添加语言标识符，以便在代码范围中启用语法突出显示。