Udostępnij przez

Plik readme pakietu w NuGet.org

  • Artykuł

Dołącz plik readme do pakietu NuGet, aby bardziej rozbudowane i bardziej informacyjne informacje dla użytkowników.

Jest to prawdopodobnie jeden z pierwszych elementów, które użytkownicy zobaczą podczas wyświetlania strony szczegółów pakietu na NuGet.org i są niezbędne, aby zrobić dobre wrażenie!

Ważne

NuGet.org obsługuje tylko pliki readme w języku Markdown i obrazy z ograniczonego zestawu domen. Zapoznaj się z naszymi dozwolonymi domenami obrazów i obsługiwanymi funkcjami języka Markdown, aby upewnić się, że plik readme jest poprawnie renderowany na NuGet.org.

Co należy uwzględnić w pliku readme?

Rozważ uwzględnienie następujących elementów w pliku readme:

  • Wprowadzenie do tego, co to jest i co robi pakiet — jakie problemy rozwiązuje?
  • Jak rozpocząć pracę z pakietem — czy istnieją jakieś konkretne wymagania?
  • Linki do bardziej kompleksowej dokumentacji, jeśli nie zostaną uwzględnione w samym pliku readme.
  • Co najmniej kilka fragmentów kodu/przykładowych obrazów.
  • Gdzie i jak zostawić opinię, taką jak link do problemów z projektem, Twitter, tracker błędów lub inną platformę.
  • Jak współtworzyć, jeśli ma to zastosowanie.

Pamiętaj, że wysokiej jakości readmes mogą być dostępne w wielu różnych formatach, kształtach i rozmiarach! Jeśli masz już pakiet dostępny na NuGet.org, prawdopodobnie masz readme.md już plik dokumentacji lub inny plik dokumentacji w repozytorium, który byłby doskonałym dodatkiem do strony szczegółów NuGet.org.

Uwaga

Przeczytaj nasz blog na temat pisania wysokiej jakości pliku README , aby zapoznać się z najlepszymi rozwiązaniami.

Podgląd pliku readme

Aby wyświetlić podgląd pliku readme przed jego uruchomieniem na NuGet.org, przekaż pakiet przy użyciu portalu internetowego Przekaż pakiet w NuGet.org i przewiń w dół do sekcji "Plik Readme" podglądu metadanych. Powinna to wyglądać następująco:

Readme File preview

Rozważ poświęcenie czasu na przejrzenie i wyświetlenie podglądu pliku readme pod kątem zgodności obrazów i obsługiwanego formatowania , aby upewnić się, że zapewnia doskonałe wrażenie dla potencjalnych użytkowników. Aby poprawić błędy w pliku readme pakietu po opublikowaniu go w NuGet.org, należy wypchnąć zaktualizowaną wersję pakietu z poprawką. Upewnienie się, że wszystko wygląda dobrze z wyprzedzeniem, może zaoszczędzić ból głowy w dół drogi.

Dozwolone domeny dla obrazów i znaczków

Ze względu na obawy dotyczące bezpieczeństwa i prywatności NuGet.org ogranicza domeny, z których można renderować obrazy i znaczki na zaufanych hostach.

NuGet.org umożliwia renderowanie wszystkich obrazów, w tym znaczków, z następujących zaufanych domen:

  • 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

Jeśli uważasz, że do listy dozwolonych należy dodać inną domenę, możesz zgłosić problem i będzie on przeglądany przez nasz zespół inżynierów w celu zachowania prywatności i zgodności z zabezpieczeniami. Obrazy ze względnymi ścieżkami lokalnymi i obrazami hostowanymi z nieobsługiwanych domen nie zostaną renderowane i wygenerują ostrzeżenie na stronie podglądu pliku readme i szczegółów pakietu, która jest widoczna tylko dla właścicieli pakietów.

Obsługiwane funkcje języka Markdown

Markdown to lekki język znaczników ze składnią formatowania zwykłego tekstu. NuGet.org readmes obsługują język Markdown zgodny ze standardem CommonMark za pośrednictwem aparatu analizy markdig.

NuGet.org obecnie obsługuje następujące funkcje języka Markdown:

Obsługujemy również wyróżnianie składni. Możesz dodać identyfikator języka, aby włączyć wyróżnianie składni w zakresach kodu.