Dela via

Paketläsning på NuGet.org

Inkludera en readme-fil i Ditt NuGet-paket för att göra paketinformationen rikare och mer informativ för dina användare!

Detta är förmodligen ett av de första elementen som användarna kommer att se när de visar din paketinformationssida på NuGet.org och är avgörande för att göra ett gott intryck!

Viktigt!

NuGet.org stöder endast skrivskyddade filer i Markdown och bilder från en begränsad uppsättning domäner. Se våra tillåtna domäner för bilder och Markdown-funktioner som stöds för att säkerställa att readme återges korrekt på NuGet.org.

Vad ska min readme innehålla?

Överväg att inkludera följande objekt i din readme:

  • En introduktion till vad ditt paket är och gör – vilka problem löser det?
  • Hur kommer du igång med ditt paket – finns det några specifika krav?
  • Länkar till mer omfattande dokumentation om den inte ingår i själva readme.
  • Minst några kodfragment/exempel eller exempelbilder.
  • Var och hur du lämnar feedback, till exempel länk till projektproblem, Twitter, felspårare eller annan plattform.
  • Så här bidrar du, om tillämpligt.

Du kan till exempel börja med det här paketets README-mall:

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

Tänk på att högkvalitativa readmes kan komma i en mängd olika format, former och storlekar! Om du redan har ett paket tillgängligt på NuGet.org är chansen stor att du redan har en readme.md eller annan dokumentationsfil på lagringsplatsen som skulle vara ett bra komplement till din NuGet.org informationssida.

Anmärkning

Läs igenom vår blogg om att skriva ett högkvalitativt README för några metodtips.

Förhandsgranska ditt readme

Om du vill förhandsgranska readme-filen innan den är live på NuGet.org laddar du upp paketet med hjälp av webbportalen Ladda upp paket på NuGet.org och rullar ned till avsnittet "Readme File" i metadataförhandsgranskningen. Den bör se ut ungefär så här:

Förhandsgranskning av Readme-fil

Överväg att ta tid att granska och förhandsgranska readme-filen för bildstandard och stödd formatering för att säkerställa att den förmedlar ett bra första intryck för potentiella användare! För att rätta till misstag i paketläsningen när det har publicerats till NuGet.org måste du skicka en uppdaterad paketversion med korrigeringen. Att se till att allt ser bra ut i förväg kan rädda dig huvudvärk på vägen.

Tillåtna domäner för bilder och märken

På grund av säkerhets- och sekretessproblem begränsar NuGet.org de domäner från vilka bilder och märken kan återges till betrodda värdar.

NuGet.org tillåter att alla bilder, inklusive märken, från följande betrodda domäner återges:

  • api.codacy.com
  • api.codeclimate.com
  • api.dependabot.com
  • api.reuse.software
  • api.travis-ci.com
  • app.codacy.com
  • app.deepsource.com
  • avatars.githubusercontent.com
  • badgen.net
  • badges.gitter.im
  • camo.githubusercontent.com
  • caniuse.bitsofco.de
  • cdn.jsdelivr.net
  • cdn.syncfusion.com
  • ci.appveyor.com
  • circleci.com
  • cloudback.it
  • codecov.io
  • codefactor.io
  • coveralls.io
  • dev.azure.com
  • flat.badgen.net
  • github.com/.../workflows/.../badge.svg
  • gitlab.com
  • i.imgur.com
  • img.shields.io
  • infragistics.com
  • isitmaintained.com
  • media.githubusercontent.com
  • opencollective.com
  • raw.github.com
  • raw.githubusercontent.com
  • snyk.io
  • sonarcloud.io
  • travis-ci.com
  • travis-ci.org
  • user-images.githubusercontent.com

Om du anser att en annan domän ska läggas till i listan över tillåtna kan du skicka in ett ärende och det kommer att granskas av vårt teknikteam för sekretess och säkerhetsefterlevnad. Bilder med relativa lokala sökvägar och bilder från domäner som inte stöds återges inte och ger en varning på sidan för förhandsgranskning av readme-filen och paketinformation som endast är synlig för paketägarna.

Markdown-funktioner som stöds

Markdown är ett förenklat märkspråk med syntax för oformaterad textformatering. NuGet.org readmes stöder CommonMark-kompatibel Markdown via Markdig-parsningsmotorn.

NuGet.org stöder för närvarande följande Markdown-funktioner:

Vi stöder även syntaxmarkering. Du kan lägga till en språkidentifierare för att aktivera syntaxmarkering i dina kodintervall.