Ler em inglês

Partilhar via

Modelo de Metadados e Markdown para documentação do .NET

  • Artigo

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

Ao criar um ficheiro de Markdown, copie o modelo incluído para um novo ficheiro, preencha os metadados conforme especificado abaixo e defina o título H1 acima para o título do artigo.

Metadados

Pode encontrar o bloco de metadados obrigatório no seguinte bloco de metadados de exemplo:

markdown 
---
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
  • Tem de colocar um espaço entre os dois pontos (:) e o valor de um elemento de metadados.
  • Os dois pontos num valor (por exemplo, um título) dividem o analisador de metadados. Neste caso, coloque o título entre aspas duplas (por exemplo, title: "Writing .NET Core console apps: An advanced step-by-step guide").
  • title (título): é apresentado nos resultados de motores de busca. O título não deve ser idêntico ao seu título H1 e deve conter 60 carateres ou menos.
  • description (descrição): resume os conteúdos do artigo. É geralmente apresentado na página de resultados da pesquisa, mas não é utilizado na classificação da pesquisa. Deve ter 115 a 145 carateres, incluindo espaços.
  • author (autor): o campo "author" deve conter o nome de utilizador do GitHub do autor.
  • ms.date: a data da última atualização importante. Atualize este campo em artigos existentes, caso tenha revisto e atualizado todo o artigo. Pequenas correções, como erros ortográficos ou semelhantes, não justificam uma atualização.

São anexados outros metadados a cada artigo, mas normalmente aplicamos a maioria dos valores de metadados ao nível da pasta, especificado em docfx.json.

Markdown básico, GFM e carateres especiais

Pode aprender as noções básicas sobre Markdown, GFM (GitHub Flavored Markdown) e extensões OPS específicas no artigo sobre Referência de Markdown.

Markdown utiliza carateres especiais como *, 'e # para formatação. Se quiser incluir um destes carateres nos seus conteúdos, tem de optar por uma de duas opções:

  • Coloque uma barra invertida à frente do caráter especial para "escapar" (por exemplo, \* para um *).
  • Utilize o código de entidade HTML para o caráter (por exemplo, * para um *).

Nomes de ficheiros

Os nomes de ficheiros utilizam as seguintes regras:

  • Contêm apenas letras minúsculas, números e hífenes.
  • Não inclua carateres de espaço nem pontuação. Utilize hífenes para separar palavras e números no nome do ficheiro.
  • Utilize verbos de ação específicos, como develop (programar), buy (comprar), build (criar), troubleshoot (resolver). Não utilize o gerúndio.
  • Não inclua palavras pequenas – a (um), and (e), the (o), in (em), or (ou), etc.
  • Têm de estar em Markdown e utilizar a extensão de nome de ficheiro .md.
  • Mantenha os nomes de ficheiros razoavelmente curtos. Fazem parte do URL para os seus artigos.

Títulos

Utilize maiúsculas tal como em frases. Utilize sempre maiúsculas na primeira palavra de um título.

Estilo de texto

Itálico
Utilize para ficheiros, pastas, caminhos (para itens mais longos, coloque-os numa linha à parte), novos termos.

Negrito
Utilize em elementos da IU.

Code
Utilize para código inline, palavras-chave de linguagem, nomes de pacotes NuGet, comandos de linhas de comandos, nomes de tabelas e colunas de base de dados e URLs que não pretenda que sejam clicáveis.

Veja o artigo geral sobre Ligações para obter informações sobre âncoras, ligações internas, ligações para outros documentos, inclusões de código e ligações externas.

A equipa de documentação do .NET utiliza as seguintes convenções:

  • Na maioria dos casos, são utilizadas ligações relativas e é desencorajada a utilização de ~/ nas ligações, já que as ligações relativas são resolvidas na origem no GitHub. No entanto, sempre que for efetuada ligação a um ficheiro num repositório dependente, utilizamos o caráter ~/ para o caminho. Uma vez que os ficheiros no repositório dependente se encontram numa localização diferente no GitHub, as ligações não serão resolvidas corretamente com as ligações relativas, independentemente de como foram escritas.
  • As especificações da linguagem C# e da linguagem do Visual Basic estão incluídas na documentação do .NET ao incluir a origem dos repositórios de linguagem. As origens de markdown são geridas nos repositórios csharplang e vblang.

As ligações para a especificação têm de apontar para os diretórios de origem onde as especificações estão incluídas. Para a linguagem C#, é ~/_csharplang/spec e para o Visual Basic, é ~/_vblang/spec, conforme o seguinte exemplo:

markdown 
[C# Query Expressions](~/_csharplang/spec/expressions.md#query-expressions)

O sistema da compilação tem algumas extensões que permitem a ligação a APIs do .NET sem ser necessário utilizar ligações externas. Pode utilizar uma das seguintes sintaxes:

  1. Ligação automática: <xref:UID> ou <xref:UID?displayProperty=nameWithType>

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

  2. Ligação markdown: [link text](xref:UID)

    Utilize quando quiser personalizar o texto da ligação apresentado.

Exemplos:

  • <xref:System.String> é representado como String
  • <xref:System.String?displayProperty=nameWithType> é representado como System.String
  • [String class](xref:System.String) é representado como String class

Para obter mais informações sobre como utilizar este notação, veja Using cross reference (Utilizar a referência cruzada).

Alguns UIDs contêm os carateres especiais ", # ou *, o valor UID tem de ser codificado em HTML como %60, %23 e %2A respetivamente. Por vezes, verá parênteses codificados, mas não são um requisito.

Exemplos:

  • System.Threading.Tasks.Task'1 torna-se 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

Pode localizar os tipos de UIDs, uma lista de sobrecarga de membros ou um membro sobrecarregado específico a partir de https://xref.learn.microsoft.com/autocomplete. A cadeia de consulta ?text=*\<type-member-name>* identifica o tipo ou membro cujos UIDs pretende ver. Por exemplo, https://xref.learn.microsoft.com/autocomplete?text=string.format obtém as sobrecargas String.Format. A ferramenta procura o parâmetro da consulta text fornecido em qualquer parte do UID. Por exemplo, pode procurar o nome do membro (ToString), nome parcial do membro (ToStri), tipo e nome do membro (Double.ToString), etc.

Se adicionar um * (ou %2A) após o UID, a ligação representa a página de sobrecarga e não uma API específica. Por exemplo, pode utilizá-lo quando quiser ligar à Lista<T>. Página Método BinarySearch de uma forma genérica em vez de uma sobrecarga específica, como Lista<T>. BinarySearch(T, IComparer<T>). Também pode utilizar * para ligar a uma página de membro quando o membro não está sobrecarregado; isto impede-o de ter de incluir a lista de parâmetros no UID.

Para ligar a uma sobrecarga de método específica, tem de incluir o nome do tipo completamente qualificado de cada parâmetro do método. Por exemplo, <xref:System.DateTime.ToString> liga ao método DateTime.ToString sem parâmetros, enquanto <xref:System.DateTime.ToString(System.String,System.IFormatProvider)> liga ao método DateTime.ToString(String,IFormatProvider ).

Para ligar a um tipo genérico, como System.Collections.Generic.List<T>, utilize o caráter " (%60) seguido do número de parâmetros de tipo genérico. Por exemplo, <xref:System.Nullable%601> liga para o tipo T> System.Nullable<, enquanto <xref:System.Func%602> liga ao delegado System.Func<T,TResult>.

Código

A melhor maneira de incluir código é incluir fragmentos de um exemplo. Crie o seu exemplo ao seguir as instruções no artigo Contributing to .NET (Contribuir para o .NET). Incluir fragmentos de programas completos garante que todo o código é executado através do nosso sistema de Integração Contínua (IC). Contudo, se precisar de mostrar algum exemplo que cause erros de execução ou no momento da compilação, pode utilizar blocos de código inline.

Para obter informações sobre a sintaxe de Markdown para mostrar código em documentos, veja Como incluir código em documentos.

Imagens

Imagem estática ou GIF animado

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

Imagem ligada

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

Vídeos

Pode incorporar vídeos do YouTube num ficheiro Markdown. Para obter o URL correto do vídeo, clique com o botão direito do rato no vídeo, selecione Copiar Código Incorporado e copie o URL do elemento <iframe>.

markdown 
> [!VIDEO <youtube_video_link>]

Por exemplo:

markdown 
> [!VIDEO https://www.youtube.com/embed/Q2mMbjw6cLA]

extensões learn.microsoft

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

Listas marcadas

Está disponível um estilo personalizado para listas. Pode compor listas com marcas de verificação verdes.

markdown 
> [!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

Isto é composto como:

  • Como criar uma aplicação .NET Core
  • Como adicionar referência ao pacote Microsoft.XmlSerializer.Generator
  • Como editar o seu MyApp.csproj para adicionar dependências
  • Como adicionar uma classe e um XmlSerializer
  • Como criar e executar a aplicação

Pode ver um exemplo de listas de verificação em ação na documentação do .NET Core.

Botões

Ligações de botões:

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

Isto é composto como:

Pode ver um exemplo de botões em ação na documentação do Visual Studio.

Passo a passo

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

Pode ver um exemplo passo a passo em ação no Guia de C#.