Compartilhar via

Leiame do pacote no NuGet.org

Inclua um arquivo leiame em seu pacote NuGet para tornar os detalhes do pacote mais completos e informativos para seus usuários!

Esse é provavelmente um dos primeiros elementos que os usuários verão quando exibirem a página de detalhes do pacote no NuGet.org e é essencial para dar uma boa impressão!

Importante

NuGet.org só dá suporte a arquivos readme em Markdown e imagens de um conjunto limitado de domínios. Consulte nossos domínios permitidos para imagens e recursos Markdown com suporte para garantir que seu README seja renderizado corretamente em NuGet.org.

O que meu arquivo readme deve incluir?

Recomenda-se a inclusão dos seguintes itens no seu readme:

  • Uma introdução ao que seu pacote é e faz - quais problemas ele resolve?
  • Como começar a usar seu pacote – há requisitos específicos?
  • Links para documentação mais abrangente caso não esteja incluída no próprio readme.
  • Pelo menos alguns snippets de código/exemplos ou imagens de exemplo.
  • Onde e como deixar comentários, como link para os problemas do projeto, Twitter, rastreador de bugs ou outra plataforma.
  • Como contribuir, se aplicável.

Por exemplo, você pode começar com este modelo README de pacote:

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

Tenha em mente que os readmes de alta qualidade podem vir em uma ampla variedade de formatos, formas e tamanhos! Se você já tiver um pacote disponível no NuGet.org, as chances são de que você já tenha um readme.md ou outro arquivo de documentação em seu repositório que seria uma ótima adição à página de detalhes do NuGet.org.

Observação

Leia em nosso blog sobre como escrever um LEIAME de alta qualidade para conferir algumas das melhores práticas.

Visualizar seu readme

Para visualizar seu arquivo Readme antes de ele estar ativo no NuGet.org, carregue seu pacote usando o portal da Web para Carregar Pacote no NuGet.org e role para baixo até a seção "Arquivo Readme" da visualização de metadados. O resultado deve ser algo como:

Visualização do arquivo Readme

Considere dedicar um tempo para examinar e visualizar seu arquivo readme para conformidade com a imagem e formatação compatível, para garantir que ele dê uma ótima primeira impressão aos usuários potenciais! Para corrigir erros no leiame do pacote depois que ele for publicado no NuGet.org, você precisará enviar por push uma versão atualizada do pacote com a correção. Garantir que tudo fique bem com antecedência pode te poupar dor de cabeça na estrada.

Domínios permitidos para imagens e selos

Devido a questões de segurança e privacidade, NuGet.org restringe os domínios dos quais imagens e selos podem ser renderizados para hosts confiáveis.

NuGet.org permite que todas as imagens, incluindo selos, dos seguintes domínios confiáveis sejam renderizadas:

  • 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 você achar que outro domínio deve ser adicionado à lista de permissões, fique à vontade para apresentar um problema e ele será revisado pela nossa equipe de engenharia quanto à conformidade de privacidade e segurança. Imagens com caminhos locais relativos e aquelas hospedadas em domínios não suportados não serão renderizadas e gerarão um aviso na pré-visualização do arquivo "readme" e na página de detalhes do pacote, visível apenas para os proprietários do pacote.

Recursos compatíveis com Markdown

O Markdown é uma linguagem de marcação leve com sintaxe de formatação de texto sem formatação. NuGet.org readmes dão suporte ao Markdown compatível com CommonMark por meio do mecanismo de análise Markdig .

NuGet.org atualmente dá suporte aos seguintes recursos do Markdown:

Também oferecemos suporte ao realce de sintaxe, você pode adicionar um identificador de idioma para habilitar o realce de sintaxe em seus intervalos de código.