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

Файл сведений о пакете на NuGet.org

  • Статья

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

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

Внимание

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

Что необходимо включить в файл сведений?

Рассмотрите возможность включения следующих элементов в файл сведений:

  • Общие сведения о том, что представляет собой пакет, и какие проблемы он решает.
  • Инструкции по началу работы с пакетом и особые требования (при наличии).
  • Ссылки на более подробную документацию, если она не включена в сам файл сведений.
  • По крайней мере несколько фрагментов кода, примеров или изображений.
  • Где и как оставить отзыв, например ссылка на проблемы проекта, Twitter, средство отслеживания ошибок или другую платформу.
  • Как помочь разработке, если применимо.

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

Примечание.

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

Предварительный просмотр файла сведений

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

Readme File preview

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

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

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