Поделиться через

Чтение пакета в NuGet.org

Включите файл readme в пакет NuGet , чтобы сделать сведения о пакете более подробными и более информативными для пользователей!

Это, скорее всего, один из первых элементов, которые пользователи увидят, когда откроют страницу сведений о пакете на NuGet.org, что важно для создания хорошего впечатления!

Это важно

NuGet.org поддерживает только файлы readme в Markdown и изображениях из ограниченного набора доменов. Ознакомьтесь с разрешёнными доменами для изображений и поддерживаемыми функциями Markdown, чтобы убедиться, что ваш файл readme правильно отображается на NuGet.org.

Что должно быть включено в мой файл 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.

Имейте в виду, что высококачественные файлы README могут иметь широкий спектр форматов, форм и размеров! Если у вас уже есть пакет, доступный на NuGet.org, возможно, у вас уже есть readme.md файл документации или другой файл документации в репозитории, который будет отличным дополнением к странице сведений о NuGet.org.

Замечание

Ознакомьтесь с нашим блогом о написании высококачественного README для некоторых рекомендаций.

Просмотрите readme

Чтобы просмотреть файл readme, прежде чем он находится в режиме реального времени в NuGet.org, отправьте пакет с помощью веб-портала "Отправить пакет" на NuGet.org и прокрутите вниз до раздела "Файл readme" предварительного просмотра метаданных. Должно отобразиться примерно следующее:

Предварительная версия файла readme

Рассмотрите возможность просмотра и профилактического просмотра вашего файла readme на соответствие изображения и поддерживаемое форматирование, чтобы убедиться, что он производит хорошее первое впечатление на потенциальных пользователей! Чтобы исправить ошибки в readme файла пакета после его публикации на 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

Если вы считаете, что в список разрешений следует добавить другой домен, пожалуйста, можете отправить проблему , и она будет рассмотрена нашими специалистами по обеспечению конфиденциальности и безопасности. Изображения с относительными локальными путями и изображениями, размещёнными на неподдерживаемых доменах, не будут отображаться и вызовут предупреждение в предварительном просмотре файла readme и на странице сведений о пакете, которое будет видно только владельцам пакетов.

Поддерживаемые функции Markdown

Markdown — это облегченный язык разметки с синтаксисом форматирования обычного текста. readme-файлы на NuGet.org поддерживают Markdown, соответствующий стандарту CommonMark, с помощью парсера Markdig.

NuGet.org в настоящее время поддерживает следующие функции Markdown:

Мы также поддерживаем выделение синтаксиса, вы можете добавить идентификатор языка, чтобы включить выделение синтаксиса в диапазонах кода.