Udostępnij za pośrednictwem

Plik readme pakietu w NuGet.org

Dołącz plik readme do pakietu NuGet, aby uczynić jego szczegóły bardziej szczegółowymi i informacyjnymi 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ę, na przykład poprzez link do zgłaszania problemów z projektem, Twitter, tracker błędów lub inną platformę.
  • Jak współtworzyć, jeśli ma to zastosowanie.

Na przykład możesz zacząć od tego szablonu README pakietu:

# 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.

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

Uwaga / Notatka

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

Podgląd twojego pliku readme

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

Podgląd pliku Readme

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 przesłać zaktualizowaną wersję pakietu zawierającą poprawkę. Upewnienie się z wyprzedzeniem, że wszystko wygląda dobrze, może zaoszczędzić ci bólu głowy w przyszłości.

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 pomocą silnika parsowania 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.