Condividi tramite

Readme del pacchetto in NuGet.org

  • Articolo

Includere un file leggimi nel pacchetto NuGet per rendere i dettagli del pacchetto più avanzati e più informativi per gli utenti.

Questo è probabilmente uno dei primi elementi che gli utenti vedranno quando visualizzano la pagina dei dettagli del pacchetto in NuGet.org ed è essenziale per fare una buona impressione!

Importante

NuGet.org supporta solo file readme in Markdown e immagini da un set limitato di domini. Vedere i domini consentiti per le immagini e le funzionalità Markdown supportate per garantire che il rendering del file readme venga eseguito correttamente in NuGet.org.

Cosa deve includere il file leggimi?

Prendere in considerazione l'inclusione degli elementi seguenti nel file leggimi:

  • Un'introduzione a cosa si trova il pacchetto e fa : quali problemi risolve?
  • Come iniziare a usare il pacchetto: sono previsti requisiti specifici?
  • Collegamenti a una documentazione più completa se non inclusa nel file leggimi stesso.
  • Almeno alcuni frammenti di codice/esempi o immagini di esempio.
  • Dove e come lasciare commenti e suggerimenti, ad esempio i collegamenti ai problemi del progetto, Twitter, bug tracker o altre piattaforme.
  • Come contribuire, se applicabile.

Tieni presente che i leggimi di alta qualità possono venire in un'ampia gamma di formati, forme e dimensioni! Se è già disponibile un pacchetto in NuGet.org, è probabile che nel repository sia già presente un readme.md file di documentazione o un altro file di documentazione che sarebbe un'ottima aggiunta alla pagina dei dettagli NuGet.org.

Nota

Leggere il blog sulla scrittura di un FILE LEGGIMI di alta qualità per alcune procedure consigliate.

Visualizzare in anteprima il file leggimi

Per visualizzare in anteprima il file leggimi prima che sia attivo in NuGet.org, caricare il pacchetto usando il portale Web Carica pacchetto in NuGet.org e scorrere verso il basso fino alla sezione "File Leggimi" dell'anteprima dei metadati. L'output dovrebbe essere simile al seguente:

Readme File preview

Prendere tempo per esaminare e visualizzare in anteprima il file leggimi per la conformità delle immagini e la formattazione supportata per assicurarsi che offra un'ottima impressione ai potenziali utenti. Per correggere gli errori nel file leggimi del pacchetto dopo la pubblicazione in NuGet.org, è necessario eseguire il push di una versione aggiornata del pacchetto con la correzione. Assicurandosi che tutto sembra buono in anticipo può risparmiare mal di testa lungo la strada.

Domini consentiti per immagini e badge

A causa di problemi di sicurezza e privacy, NuGet.org limita i domini da cui è possibile eseguire il rendering di immagini e badge agli host attendibili.

NuGet.org consente il rendering di tutte le immagini, incluse le notifiche, dai domini attendibili seguenti:

  • 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

Se si ritiene che un altro dominio debba essere aggiunto all'elenco elementi consentiti, è possibile segnalare un problema e verrà esaminato dal team di progettazione per la privacy e la conformità alla sicurezza. Il rendering delle immagini con percorsi locali e immagini relativi ospitati da domini non supportati non verrà eseguito e genererà un avviso nella pagina di anteprima del file leggimi e dei dettagli del pacchetto visibili solo ai proprietari del pacchetto.

Funzionalità markdown supportate

Markdown è un linguaggio di tipo Lightweight Markup Language (LML) con sintassi di formattazione in testo normale. NuGet.org readmes supportano Markdown conforme a CommonMark tramite il motore di analisi Markdig .

NuGet.org attualmente supporta le funzionalità markdown seguenti:

È anche supportata l'evidenziazione della sintassi. È possibile aggiungere un identificatore di linguaggio per abilitare l'evidenziazione della sintassi negli intervalli di codice.