Compartilhar via

Metadados e modelo markdown para documentos do .NET

Este modelo dotnet/docs contém exemplos de sintaxe markdown e orientação sobre como definir os metadados.

Ao criar um arquivo Markdown, copie o modelo incluído para um novo arquivo, preencha os metadados conforme especificado abaixo e defina o título H1 acima para 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ê deve ter um espaço entre os dois pontos (:) e o valor de um elemento de metadados.
  • Dois-pontos em um valor (por exemplo, um título) quebram o analisador de metadados. Nesse caso, envolva o título com aspas duplas (por exemplo, title: "Writing .NET Core console apps: An advanced step-by-step guide").
  • título: Aparece nos resultados do mecanismo de pesquisa. O título não deve ser idêntico ao título no título H1 e deve conter 60 caracteres ou menos.
  • descrição: resume o conteúdo do artigo. Geralmente, ele é mostrado na página de resultados da pesquisa, mas não é usado para a classificação de pesquisa. Seu comprimento deve ser de 115 a 145 caracteres, incluindo espaços.
  • autor: O campo autor deve conter o nome de usuário do GitHub do autor.
  • ms.date: a data da última atualização significativa. Atualize isso nos artigos existentes se você revisou e atualizou todo o artigo. Pequenas correções, como erros de digitação ou similares, não justificam uma atualização.

Outros metadados são anexados a cada artigo, mas normalmente aplicamos a maioria 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 de Markdown, GitHub Flavored Markdown (GFM) e extensões específicas do OPS no artigo de referência de Markdown.

Markdown usa caracteres especiais como *, 'e # para formatação. Se você quiser incluir um desses caracteres em seu conteúdo, deverá fazer uma das duas coisas:

  • Coloque uma barra invertida antes do caractere especial para "escapar" (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 ou caracteres de pontuação. Use os hifens para separar palavras e números no nome do arquivo.
  • Use verbos de ação específicos, como desenvolver, comprar, compilar, solucionar problemas. Sem palavras com o sufixo -ing.
  • Sem palavras pequenas - não inclua um, e, o, em, ou, etc.
  • Deve estar em Markdown e utilizar a extensão de arquivo .md.
  • Mantenha os nomes de arquivo razoavelmente curtos. Eles fazem parte da URL de seus artigos.

Títulos

Use a capitalização em estilo de frase. Sempre capitalize a primeira palavra de um título.

Estilo de texto

Italics
Use para arquivos, pastas, caminhos (para itens longos, divididos em sua própria linha), novos termos.

Bold
Use para elementos de interface do usuário.

Code
Use para código embutido, palavras-chave de linguagem, nomes de pacote NuGet, comandos de linha de comando, nomes de tabela e coluna de banco de dados e URLs que você não deseja que sejam clicáveis.

Consulte o artigo geral 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 das vezes, usamos links relativos e desencorajamos o uso de links ~/ porque links relativos são resolvidos na origem deles no GitHub. No entanto, sempre que vinculamos a um arquivo em um repositório dependente, usamos o ~/ caractere para fornecer o caminho. Como os arquivos do repositório dependente estão em um local diferente no GitHub, os links relativos não serão resolvidos corretamente, independentemente de como foram escritos.
  • A especificação da linguagem C# e a especificação da linguagem Visual Basic são incluídas nos documentos do .NET, incluindo a origem dos repositórios de idiomas. As fontes markdown são gerenciadas nos repositórios csharplang e vblang .

Os links para a especificação devem apontar para os diretórios de origem em que essas 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 vincular a APIs do .NET sem precisar usar links externos. Use uma das seguintes sintaxes:

  1. Link automático: <xref:UID> ou <xref:UID?displayProperty=nameWithType>

    O displayProperty parâmetro de consulta produz um texto de link totalmente qualificado. Por padrão, o texto do link mostra apenas o nome do membro ou do tipo.

  2. Link do Markdown: [link text](xref:UID)

    Use quando quiser personalizar o texto do link exibido.

Exemplos:

Para obter mais informações sobre como usar essa notação, consulte Usando referência cruzada.

Alguns UIDs contêm os caracteres especiais ', # ou *, o valor da UID precisa ser codificado em HTML como %60e%23, %2A respectivamente. Às vezes, você verá parênteses codificados, mas não é um requisito.

Exemplos:

  • System.Threading.Tasks.Task'1 se torna System.Threading.Tasks.Task%601
  • System.Exception.#ctor torna-se System.Exception.%23ctor
  • System.Lazy'1.#ctor(System.Threading.LazyThreadSafetyMode) torna-se System.Lazy%601.%23ctor%28System.Threading.LazyThreadSafetyMode%29

Se você adicionar um * (ou %2A) após a UID, o link representará a página de sobrecarga e não uma API específica. Por exemplo, você pode usá-lo quando quiser vincular à página do método List<T>.BinarySearch de uma maneira genérica em vez de uma sobrecarga específica, como List<T>.BinarySearch(T, IComparer<T>). Você também pode usar * para vincular a uma página de membro quando o membro não estiver sobrecarregado; isso salva você de ter que incluir a lista de parâmetros na UID.

Para vincular a uma sobrecarga de método específica, você deve incluir o nome de tipo totalmente qualificado de cada um dos parâmetros do método. Por exemplo, <xref:System.DateTime.ToString> vincula-se ao método DateTime.ToString sem parâmetros, enquanto <xref:System.DateTime.ToString(System.String,System.IFormatProvider)> vincula ao método DateTime.ToString(String, IFormatProvider).

Para vincular a um tipo genérico, como System.Collections.Generic.List<T>, use o caractere ' (%60) seguido pelo número de parâmetros de tipo genérico. Por exemplo, <xref:System.Nullable%601> liga para o System.Nullable<T> tipo, enquanto <xref:System.Func%602> liga para o delegado System.Func<T, TResult>.

Code

A melhor maneira de incluir código é incluir trechos de um exemplo funcional. Crie seu exemplo seguindo as instruções no artigo colaborando com .NET. A inclusão de snippets de programas completos garante que todo o código seja executado por meio de nosso sistema de CI (Integração Contínua). No entanto, se você precisar mostrar algo que cause erros de tempo de compilação ou de runtime, poderá usar blocos de código embutidos.

Para obter informações sobre a sintaxe markdown para mostrar código em documentos, consulte 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)

Videos

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 <iframe> elemento.

> [!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 o GitHub Flavored Markdown.

Listas verificadas

Um estilo personalizado está 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 é renderizado como:

  • 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 criar e executar o aplicativo

Você pode ver um exemplo de listas marcadas em ação nos documentos do .NET Core.

Buttons

Links de botão:

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

Isso é renderizado como:

links de botão

Você pode ver um exemplo de botões em ação nos documentos do Visual Studio.

Etapas passo a passo

>[!div class="step-by-step"]
> [Pre](../docs/csharp/expression-trees-interpreting.md)
> [Next](../docs/csharp/expression-trees-translating.md)

Você pode ver um exemplo de etapas passo a passo em ação no Guia do C#.

  • Last updated on