Sdílet prostřednictvím

Soubor s informacemi balíčku na NuGet.org

Do balíčku NuGet zahrňte soubor readme, který poskytne vašim uživatelům podrobnější a informativnější informace o balíčku.

To je pravděpodobně jeden z prvních prvků, které uživatelé uvidí, když si zobrazí stránku s podrobnostmi balíčku na NuGet.org a je nezbytné udělat dobrý dojem!

Důležité

NuGet.org podporuje pouze soubory readme v Markdownu a obrázky z omezené sady domén. Podívejte se na naše povolené domény pro obrázky a podporované funkce Markdownu , abyste zajistili, že se váš soubor readme správně vykresluje na NuGet.org.

Co má můj readme obsahovat?

Zvažte zahrnutí následujících položek do souboru readme:

  • Úvod k tomu, co je balíček a co dělá – jaké problémy řeší?
  • Jak začít s balíčkem – existují nějaké konkrétní požadavky?
  • Odkazy na komplexnější dokumentaci, pokud nejsou zahrnuty do samotného souboru readme.
  • Alespoň několik fragmentů kódu/ ukázek nebo ukázkových obrázků.
  • Kde a jak zanechat zpětnou vazbu, například odkaz na problémy s projektem, Twitter, sledování chyb nebo jinou platformu
  • Jak přispívat, pokud je to možné.

Můžete například začít s touto šablonou README balíčku:

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

Mějte na paměti, že vysoce kvalitní readmes mohou být v široké škále formátů, podob a velikostí! Pokud už máte balíček dostupný na NuGet.org, je pravděpodobné, že už máte readme.md v úložišti soubor dokumentace nebo jiný soubor dokumentace, který by byl skvělým doplňkem na stránce s podrobnostmi NuGet.org.

Poznámka:

Přečtěte si náš blog o psaní vysoce kvalitního souboru README pro některé osvědčené postupy.

Zobrazit náhled souboru readme

Pokud chcete zobrazit náhled souboru readme před tím, než bude aktivní na NuGet.org, nahrajte balíček pomocí webového portálu Nahrát balíček na NuGet.org a posuňte se dolů do části Soubor readme náhledu metadat. Měla by vypadat přibližně takto:

Náhled souboru Readme

Zvažte, zda si najdete čas na kontrolu a náhled souboru readme, abyste zajistili soulad s požadavky na obrázky a podporované formátování, čímž zajistíte, že poskytne potenciálním uživatelům skvělý první dojem. Pokud chcete opravit chyby v souboru readme balíčku po publikování do NuGet.org, budete muset odeslat aktualizovanou verzi balíčku s opravou. Může vám ušetřit bolest hlavy v budoucnu, pokud se předem ujistíte, že všechno vypadá dobře.

Povolené domény pro obrázky a odznáčky

Vzhledem k obavám o zabezpečení a ochranu osobních údajů omezuje NuGet.org domény, ze kterých mohou být obrázky a odznáčky zobrazovány, pouze na důvěryhodné hostitele.

NuGet.org umožňuje vykreslení všech imagí, včetně odznáků, z následujících důvěryhodných domén:

  • 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

Pokud máte pocit, že by do seznamu povolených měla být přidána jiná doména, neváhejte podat problém a náš technický tým zkontroluje dodržování předpisů v oblasti ochranyosobních Obrázky s relativními místními cestami a obrázky hostovanými z nepodporovaných domén se nevykreslí a na stránce náhledu souboru readme a podrobností balíčku, která se zobrazí pouze vlastníkům balíčků, se zobrazí upozornění.

Podporované funkce Markdownu

Markdown je jednoduchý jazyk využívající značky se syntaxí formátování prostého textu. NuGet.org readmes podporují Markdown kompatibilní s CommonMark prostřednictvím modulu pro analýzu Markdigu .

NuGet.org aktuálně podporuje následující funkce Markdownu:

Podporujeme také zvýrazňování syntaxe. Můžete přidat identifikátor jazyka, který umožňuje zvýrazňování syntaxe ve vašem kódu.

  • Last updated on