Treinamento
Módulo
Comunicar-se com eficiência no GitHub usando o Markdown - Training
Saiba como usar Markdown para se comunicar de maneira breve, clara e expressiva.
Não há mais suporte para esse navegador.
Atualize o Microsoft Edge para aproveitar os recursos, o suporte técnico e as atualizações de segurança mais recentes.
Este modelo de dotnet/docs contém exemplos de sintaxe de Markdown, bem como diretrizes para configurar os metadados.
Ao criar um arquivo markdown, copie o modelo incluído em um novo arquivo, preencha os metadados conforme especificado abaixo e defina o cabeçalho H1 acima como o título do artigo.
O bloco de metadados necessário está no seguinte bloco de metadados de exemplo:
---
title: [ARTICLE TITLE]
description: [usually a summary of your first paragraph. It gets displayed in search results, and can help drive the correct traffic if well written.]
author: [GITHUB USERNAME]
ms.date: [CREATION/UPDATE DATE - mm/dd/yyyy]
---
# The H1 should not be the same as the title, but should describe the article contents
title: "Writing .NET Core console apps: An advanced step-by-step guide"
).Outros metadados são anexados a cada artigo, mas normalmente nós aplicamos a maior parte dos valores de metadados no nível da pasta, especificado em docfx.json.
Você pode aprender as noções básicas das extensões específicas de Markdown, GFM (GitHub Flavored Markdown) e OPS no artigo Referência de Markdown.
O Markdown usa caracteres especiais como *, `, e # f para formatação. Se quiser incluir um desses caracteres em seu conteúdo, você precisará aditar uma das duas medidas a seguir:
\*
para um *).*
para um *).Os nomes de arquivo usam as seguintes regras:
Use a capitalização com estilo de frase. Sempre coloque em maiúsculas a primeira palavra de um cabeçalho.
Itálico
Use para arquivos, pastas, caminhos (para itens longos, divida cada um em sua própria linha), novos termos.
Negrito
Use para elementos da interface do usuário.
Code
Use para código embutido, palavras-chave da linguagem, nomes de pacotes NuGet, comandos da linha de comando, nomes de coluna e tabelas de banco de dados e URLs que você não deseja que sejam clicáveis.
Confira o artigo sobre Links para obter informações sobre âncoras, links internos, links para outros documentos, inclusões de código e links externos.
A equipe de documentos do .NET usa as seguintes convenções:
~/
nos links porque links relativos são resolvidos na origem no GitHub. No entanto, sempre que criamos um link para um arquivo em um repositório dependente, usamos o caractere ~/
para fornecer o caminho. Como os arquivos no repositório dependente ficam em uma localização diferente no GitHub, os links não serão resolvidos corretamente com os links relativos, independentemente de como foram escritos.Links para as especificações devem apontar para os diretórios de origem em que as especificações estão incluídas. Para C#, é ~/_csharplang/spec e para VB, é ~/_vblang/spec, como no exemplo a seguir:
[C# Query Expressions](~/_csharplang/spec/expressions.md#query-expressions)
O sistema de build tem algumas extensões que nos permitem criar links para APIs do .NET sem precisar usar links externos. Você pode usar uma das seguintes sintaxes:
Vincular automaticamente: <xref:UID>
ou <xref:UID?displayProperty=nameWithType>
O parâmetro de consulta displayProperty
produz um texto de link totalmente qualificado. Por padrão, o texto do link mostra apenas o nome do membro ou do tipo.
Link de Markdown: [link text](xref:UID)
Use para personalizar o texto do link exibido.
Exemplos:
<xref:System.String>
é renderizado como String<xref:System.String?displayProperty=nameWithType>
é renderizado como System.String[String class](xref:System.String)
é renderizado como classe StringPara saber mais sobre como usar essa notação, confira Uso da referência cruzada.
Alguns UIDs contêm os caracteres especiais `, # ou *, o valor do UID deve ser codificado em HTML como %60
, %23
e ,%2A
, respectivamente. Às vezes, você verá parênteses codificados, mas, isso não é um requisito.
Exemplos:
System.Threading.Tasks.Task%601
System.Exception.%23ctor
System.Lazy%601.%23ctor%28System.Threading.LazyThreadSafetyMode%29
Você pode encontrar os UIDs dos tipos, uma lista de sobrecarga de membros ou um membro com sobrecarga particular de https://xref.learn.microsoft.com/autocomplete
. A cadeia de caracteres de consulta ?text=*\<type-member-name>*
identifica o tipo ou o membro cujos UIDs você gostaria de ver. Por exemplo, https://xref.learn.microsoft.com/autocomplete?text=string.format
recupera as sobrecargas de String.Format. A ferramenta pesquisa pelo parâmetro de consulta text
fornecido em qualquer parte do UID. Por exemplo, você pode pesquisar pelo nome do membro (ToString), pelo nome do membro parcial (ToStri), pelo nome e tipo do membro (Double.ToString) etc.
Se você adicionar um * (ou %2A
) depois do UID, o link representará a página de sobrecarga, e não uma API específica. Por exemplo, você pode usar isso quando deseja vincular à página do Método List<T>.BinarySearch de uma maneira genérica, em vez de usar uma sobrecarga específica, como List<T>.BinarySearch(T, IComparer<T>). Você pode usar * para criar um link para uma página de membro quando o membro não está sobrecarregado; com isso, você não precisa incluir a lista de parâmetros no UID.
Para vincular a uma sobrecarga de método específico, você precisa incluir o nome do tipo totalmente qualificado de cada um dos parâmetros do método. Por exemplo, <xref:System.DateTime.ToString> é vinculado ao método DateTime.ToString sem parâmetro, enquanto <xref:System.DateTime.ToString(System.String,System.IFormatProvider)> é vinculado ao método DateTime.ToString(String,IFormatProvider).
Para vincular a um tipo genérico, como System.Collections.Generic.List<T>, você usa o caractere (%60
) seguido do número de parâmetros de tipo genérico. Por exemplo, <xref:System.Nullable%601>
vincula ao tipo System.Nullable<T>>, enquanto vincula ao delegado <xref:System.Func%602>
System.Func<T,TResult>.
A melhor maneira de incluir código é incluir snippets de um exemplo em funcionamento. Crie seu exemplo seguindo as instruções no artigo sobre contribuição com o .NET. Incluir snippets de programas inteiros garante que todo o código passe por nosso sistema de CI (Integração Contínua). No entanto, se precisar mostrar algo que causa erros de runtime ou tempo de compilação, você poderá usar blocos de código embutido.
Para saber mais sobre a sintaxe Markdown para mostrar código em documentos, confira Como incluir código em documentos.

[](https://dot.net)
Você pode inserir vídeos do YouTube em um arquivo Markdown. Para obter a URL correta do vídeo, clique com o botão direito do mouse no vídeo, selecione Copiar Código de Inserção e copie a URL do elemento <iframe>
.
> [!VIDEO <youtube_video_link>]
Por exemplo:
> [!VIDEO https://www.youtube.com/embed/Q2mMbjw6cLA]
learn.microsoft fornece algumas extensões adicionais para GitHub Flavored Markdown.
Há um estilo personalizado disponível para listas. Você pode renderizar listas com marcas de verificação verdes.
> [!div class="checklist"]
> * How to create a .NET Core app
> * How to add a reference to the Microsoft.XmlSerializer.Generator package
> * How to edit your MyApp.csproj to add dependencies
> * How to add a class and an XmlSerializer
> * How to build and run the application
Isso será renderizado da seguinte forma:
Você pode ver um exemplo das listas verificadas em ação nos Documentos do .NET Core.
Links de botão:
> [!div class="button"]
> [button links](dotnet-contribute.md)
Isso será renderizado da seguinte forma:
Você pode ver um exemplo dos botões em ação nos Documentos do Visual Studio.
>[!div class="step-by-step"]
> [Pre](../docs/csharp/expression-trees-interpreting.md)
> [Next](../docs/csharp/expression-trees-translating.md)
Você pode ver um exemplo das instruções passo a passo em ação no Guia de C#.
Treinamento
Módulo
Comunicar-se com eficiência no GitHub usando o Markdown - Training
Saiba como usar Markdown para se comunicar de maneira breve, clara e expressiva.