Soubor readme balíčku na NuGet.org

Článek
02/07/2024

Do balíčku NuGet zahrňte soubor readme, který uživatelům zpřesní a zpřesní podrobnosti 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 jen soubory readme v Markdownu a obrázky z omezené sady domén. Podívejte se na naše povolené domény obrázků a podporovaných funkcí 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 motivu 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ějte na paměti, že vysoce kvalitní readmes mohou být v široké škále formátů, obrazců 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.

Zobrazení náhledu 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 ve verzi Preview metadat. Měla by vypadat přibližně takto:

Readme File preview

Zvažte čas, než zkontrolujete a zobrazíte náhled souboru readme, abyste zajistili dodržování předpisů obrázku a podporované formátování , abyste měli jistotu, že potenciálním uživatelům poskytne 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. Ujistěte se, že všechno vypadá dobře předem, může ušetřit bolest hlavy dolů po silnici.

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

Vzhledem k obavám o zabezpečení a ochranu osobních údajů NuGet.org omezuje domény, ze kterých se dají obrázky a odznáčky vykreslit důvěryhodným hostitelům.

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

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í se standardem 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.