Fichier Lisez-moi du package sur NuGet.org

  • Article

Incluez un fichier Lisez-moi dans votre package NuGet pour enrichir les détails de votre package et les rendre plus informatifs pour vos utilisateurs !

C’est probablement l’un des premiers éléments que les utilisateurs verront lorsqu’ils afficheront la page des détails de votre package sur NuGet.org. Cet élément est essentiel pour faire une bonne impression !

Important

NuGet.org prend uniquement en charge les fichiers Lisez-moi dans Markdown et les images provenant d’un ensemble limité de domaines. Consultez les domaines autorisés pour les images et fonctionnalités Markdown prises en charge pour vous assurer que votre fichier Lisez-moi s’affiche correctement sur NuGet.org.

Que dois-je inclure dans mon fichier Lisez-moi ?

Pensez à inclure les éléments suivants dans votre fichier Lisez-moi :

  • Une présentation de ce que votre package est et ce qu’il fait, et les problèmes qu’il résout.
  • Un guide de démarrage pour votre package, les exigences liées à votre package s’il y en a.
  • Des liens vers une documentation plus complète si elle n’est pas incluse dans le fichier Lisez-moi lui-même.
  • Quelques extraits de code/exemples ou des images d’exemple.
  • Où et comment laisser des commentaires, par exemple un lien vers les problèmes du projet, vers Twitter, vers un traqueur de bogues ou vers d’autres plateformes.
  • Comment contribuer, si applicable.

Gardez à l’esprit que les fichiers lisez-moi de haute qualité peuvent avoir un large éventail de formats, de formes et de tailles ! Si vous disposez déjà d’un package disponible sur NuGet.org, il est probable que vous disposiez déjà d’un readme.md ou d’un autre fichier de documentation dans votre référentiel. L’ajouter à la page de détail sur NuGet.org serait une excellente chose.

Remarque

Lisez notre blog sur l’écriture d’un fichier LISEZ-MOI de haute qualité pour certaines meilleures pratiques.

Afficher un aperçu du fichier Lisez-moi

Pour afficher un aperçu de votre fichier Lisez-moi avant qu’il ne soit actif sur NuGet.org, utilisez le portail web Charger votre projet sur NuGet.org et faites défiler la page vers le bas jusqu’à la section « Fichier Lisez-moi » de l’aperçu des métadonnées. Il doit se présenter comme suit :

Readme File preview

Prenez le temps de passer en revue et d’afficher un aperçu de votre fichier Lisez-moi vérifier que vos images sont conformes et que le format est pris en charge. Cela vous assurera de donner une bonne première impression à vos potentiels utilisateurs ! Pour corriger les erreurs sur votre fichier lisez-moi de package une fois qu’il a été publié sur NuGet.org, vous devez envoyer une version de package mise à jour avec le correctif. S’assurer que tout semble bon avant de publier vous évitera bon nombre de migraines.

Domaines autorisés pour les images et les badges

En raison de problèmes de sécurité et de confidentialité, NuGet.org limite les domaines à partir desquels les images et les badges peuvent être affichés sur les hôtes approuvés.

NuGet permet à toutes les images et tous les badges fournis par les domaines approuvés suivant d’être affichés :

  • 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

Si vous pensez qu’un autre domaine devrait être ajouté à la liste verte, n’hésitez pas à signaler un problème et il sera examiné par notre équipe d’ingénieurs vérifier pour la conformité en terme de confidentialité et de sécurité. Les images avec des chemins d’accès locaux relatifs et les images hébergées à partir de domaines non pris en charge ne sont pas affichées. Ces images renvoient un avertissement sur la page d’aperçu du fichier Lisez-moi et sur la page de détails du package qui n’est visible que pour les propriétaires du package.

Fonctionnalités Markdown prises en charge

Markdown est un langage de balisage léger avec une syntaxe de mise en forme en texte brut. Les fichiers Lisez-moi NuGet.org prennent en charge le Markdown conforme à CommonMark grâce au moteur d’analyse Markdig.

NuGet.org prend actuellement en charge les fonctionnalités Markdown suivantes :

Nous prenons également en charge la mise en surbrillance de la syntaxe. Vous pouvez ajouter un identificateur de langue pour activer la mise en surbrillance de la syntaxe dans vos étendues de code.