Condividi tramite

Readme del pacchetto su NuGet.org

Include un file readme nel pacchetto NuGet per arricchire i dettagli del pacchetto e renderli 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 dovrebbe includere il mio file README?

Considera di includere i seguenti elementi nel tuo file leggimi:

  • Un'introduzione a cosa è e cosa fa il pacchetto: quali problemi risolve?
  • Come iniziare a usare il pacchetto: sono previsti requisiti specifici?
  • Fornire collegamenti a una documentazione più completa se non inclusa nel readme 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, dove applicabile.

Ad esempio, è possibile iniziare con questo modello README del pacchetto:

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

Tieni presente che i file README di alta qualità possono essere 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.

Annotazioni

Leggi il blog sulla scrittura di un FILE LEGGIMI di alta qualità per alcune delle migliori pratiche.

Visualizzare in anteprima il file leggimi

Per visualizzare in anteprima il file leggimi prima che sia attivo su 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. Dovrebbe apparire simile a questo:

Anteprima del file Leggimi

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. Assicurarsi che tutto sia a posto in anticipo può evitare mal di testa in futuro.

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 relativi e delle immagini ospitate da domini non supportati non verrà eseguito e genererà un avviso nell'anteprima del file "leggimi" e nella pagina 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 supporta i file README in 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.