Modelo de metadados e Markdown para documentos do .NET

Artigo
08/09/2023

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.

Metadados

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

Você precisa ter um espaço entre os dois-pontos (:) e o valor de um elemento de metadados.
Os dois-pontos em um valor (por exemplo, um título) interrompem o analisador de metadados. Nesse caso, coloque o título entre aspas duplas (por exemplo, title: "Writing .NET Core console apps: An advanced step-by-step guide").
title: Aparece nos resultados do mecanismo de pesquisa. O título não deve ser idêntico ao título em seu cabeçalho H1 e deve contar no máximo 60 caracteres.
description: Resume o conteúdo do artigo. Normalmente, é mostrado na página de resultados da pesquisa, mas não é usado para classificação na pesquisa. O tamanho deve ser de 115 a 145 caracteres, incluindo os espaços.
author: O campo de autor deve conter o nome de usuário do GitHub do autor.
ms.date: A data da última atualização significativa. Atualize em artigos existentes se você tiver revisado e atualizado o artigo inteiro. Correções pequenas, como de erros de digitação ou semelhante, não garantem uma atualização.

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.

Markdown básico, GFM e caracteres especiais

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:

Coloque uma barra invertida antes do caractere especial como forma de "escape" (por exemplo, \* para um *).
Use o Código de entidade HTML para o caractere (por exemplo, * para um *).

Nomes de arquivo

Os nomes de arquivo usam as seguintes regras:

Contêm apenas letras minúsculas, números e hifens.
Sem espaços nem caracteres de pontuação. Usar os hifens para separar palavras e números no nome do arquivo.
Usar verbos de ação específicos, como desenvolver, comprar, compilar, solucionar problemas. Sem palavras terminando em -ndo.
Sem palavras pequenas – não inclua um, uma, e, o, a, em, ou, etc.
Deve estar em Markdown e usar a extensão de arquivo .md.
Manter os nomes de arquivo razoavelmente curtos. Eles fazem parte da URL de seus artigos.

Títulos

Use a capitalização com estilo de frase. Sempre coloque em maiúsculas a primeira palavra de um cabeçalho.

Estilo do texto

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.

Links

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:

Na maioria dos casos, usamos os links relativos e não incentivamos o uso de ~/ 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.
A especificação da linguagem C# e a especificação da linguagem de Visual Basic são incluídas nos documentos do .NET incluindo a origem dos repositórios de linguagem. As origens de Markdown são gerenciadas nos repositórios csharplang e vblang.

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)

Links para APIs

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 String

Para 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`1 se torna System.Threading.Tasks.Task%601
System.Exception #ctor se torna System.Exception.%23ctor
System.Lazy`1.#ctor(System.Threading.LazyThreadSafetyMode) becomes 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>.

Código

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.

Imagens

Imagem estática ou GIF animado

![this is the alt text](../images/Logo_DotNet.png)

Imagem vinculada

[![alt text for linked image](../images/Logo_DotNet.png)](https://dot.net)

Vídeos

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]

extensões learn.microsoft

learn.microsoft fornece algumas extensões adicionais para GitHub Flavored Markdown.

Listas com caixas de seleção

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:

Como criar um aplicativo .NET Core
Como adicionar uma referência ao pacote Microsoft.XmlSerializer.Generator
Como editar seu MyApp.csproj para adicionar dependências
Como adicionar uma classe e um XmlSerializer
Como compilar e executar o aplicativo

Você pode ver um exemplo das listas verificadas em ação nos Documentos do .NET Core.

Botões

Links de botão:

> [!div class="button"]
> [button links](dotnet-contribute.md)