Práticas recomendadas do Markdown

Este artigo fornece orientações específicas para o uso de Markdown em nossa documentação. Não se trata de um tutorial sobre Markdown. Se você precisar de um tutorial sobre Markdown, consulte este Folha de consulta de markdown.

O pipeline de build que cria nossa documentação usa markdig para processar os documentos do Markdown. O markdig analisa os documentos com base nas regras de especificação do CommonMark mais recentes. O OPS segue a especificação CommonMark e acrescenta algumas extensões para recursos específicos da plataforma, como tabelas e alertas.

A especificação CommonMark é mais rígida quanto à construção de alguns elementos Markdown. Preste muita atenção aos detalhes fornecidos neste documento.

Usamos a extensão markdownlint no VS Code para aplicar nossas regras de estilo e formatação. Essa extensão é instalada como parte do Pacote de criação do Learn.

Linhas em branco, espaços e tabulações

As linhas em branco também sinalizam o fim de um bloco em Markdown.

• Coloque um único espaço em branco entre blocos Markdown de tipos diferentes, por exemplo, entre um parágrafo e uma lista ou cabeçalho.
• Não use mais de uma linha em branco. Várias linhas em branco são renderizadas como uma única linha em branco no HTML, portanto, as linhas em branco adicionais são desnecessárias.
• Não use várias linhas em branco consecutivas em um bloco de código, pois as linhas em branco consecutivas quebram o bloco de código.

O espaçamento é importante em Markdown.

• Remova espaços extras no final das linhas. Os espaços à direita podem mudar a maneira como o Markdown é renderizado.
• Sempre use espaços em vez de guias (guias complexas).

Títulos e cabeçalhos

Use Cabeçalhos ATX somente (estilo #, em oposição a = ou cabeçalhos de estilo -).

• Uso de maiúsculas e minúsculas – apenas nomes próprios e a primeira letra de um título ou cabeçalho devem ser escritos em maiúsculas
• Inclua um espaço simples entre os # e a primeira letra do cabeçalho
• Envolva os cabeçalhos com uma única linha em branco
• Não use mais de um H1 por documento
  • Deve ser o primeiro cabeçalho
  • Ele deve corresponder ao título do artigo
• Incrementar os níveis de cabeçalho em um, sem pular níveis
• Limitar a profundidade a H3 ou H4
• Evite usar negrito ou outras marcações nos cabeçalhos

Limite o comprimento da linha a 100 caracteres

Para artigos conceituais e referência de cmdlet, limite as linhas a 100 caracteres. Para artigos about_, limite o comprimento da linha a 79 caracteres. Limitar o comprimento da linha melhora a legibilidade dos diffs e do histórico do git. Também facilita a contribuição de outros escritores.

Use a extensão Refluxo markdown no VS Code para fazer refluxo dos parágrafos para que se ajustem ao comprimento de linha prescrito.

Alguns tipos de conteúdo não podem facilmente serem realizados refluxos. Por exemplo, o código dentro dos blocos de código também pode ser difícil de fazer refluxo, dependendo do conteúdo e da linguagem do código. Não é possível refazer o fluxo de uma tabela. Nesses casos, use seu bom senso para manter o conteúdo o mais próximo possível do limite de 100 caracteres.

Ênfase

Para dar ênfase, o Markdown suporta negrito e itálico. O Markdown permite que você use * ou _ para marcar a ênfase. No entanto, para ser consistente e mostrar intenção:

• Usar ** para negrito
• Usar _ para itálico

Seguir esse padrão facilita a compreensão da intenção da marcação quando há uma mistura de negrito e itálico em um documento.

Listas

Se sua lista tiver várias frases ou parágrafos, considere usar um cabeçalho de subnível em vez de uma lista.

Envolva as listas com uma única linha em branco.

Listas não ordenadas

• Não termine os itens da lista com um ponto final, a menos que eles contenham várias frases.
• Use o caractere de hífen (-) para marcadores de itens de lista para evitar confusão com a marcação de ênfase que usa o asterisco (*).
• Para incluir um parágrafo ou outros elementos em um item de marcador, insira uma quebra de linha e alinhe o recuo com o primeiro caractere após o marcador.

Por exemplo:

This is a list that contains child elements under a bullet item.

- First bullet item

  Sentence explaining the first bullet.

  - Child bullet item

    Sentence explaining the child bullet.

- Second bullet item
- Third bullet item

Esta é uma lista que contém elementos filhos em um item de marcador.

• Primeiro item de marcador

  Frase explicando o primeiro marcador.

  • Item de marcador filho

    Frase que explica o marcador filho.

• Segundo item de marcador

• Terceiro item de marcador

Listas ordenadas

• Todos os itens em uma lista numerada devem usar o número 1. em vez de incrementar cada item.
  • A renderização de Markdown incrementa o valor automaticamente.
  • Isso facilita a reorganização dos itens e padroniza o recuo do conteúdo subordinado.
• Para incluir um parágrafo ou outros elementos em um item numerado, alinhe o recuo com o primeiro caractere após o número do item.

Por exemplo:

1. For the first element, insert a single space after the `1`. Long sentences should be wrapped to
   the next line and must line up with the first character after the numbered list marker.

   To include a second element, insert a line break after the first and align indentations. The
   indentation of the second element must line up with the first character after the numbered list
   marker.

1. The next numbered item starts here.

O Markdown resultante é renderizado da seguinte maneira:

1. Para o primeiro elemento, insira um espaço simples após o 1. Frases longas devem ser quebradas na próxima linha e devem ser alinhadas com o primeiro caractere após o marcador de lista numerada.

   Para incluir um segundo elemento, insira uma quebra de linha após o primeiro e alinhe os recuos. O recuo do segundo elemento deve ser alinhado com o primeiro caractere após o marcador de lista numerada.

2. O próximo item numerado começa aqui.

Imagens

A sintaxe que deve ser incluída em uma imagem é:

![[alt text]](<folderPath>)

Example:
![Introduction](./media/overview/Introduction.png)

Em que alt text é uma breve descrição da imagem, e <folderPath> é um caminho relativo para a imagem.

• O texto alternativo é necessário para dar suporte a leitores de tela para deficientes visuais.
• As imagens devem ser armazenadas em uma pasta media/<article-name> dentro de outra pasta que contém o artigo.
  • Crie uma pasta que corresponda ao nome de arquivo do artigo na pasta media. Copie as imagens desse artigo para a nova pasta.
• Não compartilhe imagens entre artigos.
  • Se uma imagem for usada por vários artigos, cada pasta deverá ter uma cópia dessa imagem.
  • Isso evita que a alteração de uma imagem em um artigo afete outro.

Os seguintes tipos de arquivos de imagem são compatíveis: *.png, *.gif, *.jpeg, *.jpg, *.svg

Extensão Markdown - Caixas de alerta

O Pacote de criação do Learn contém ferramentas que oferecem suporte a recursos exclusivos do nosso sistema de publicação. Os alertas são uma extensão do Markdown para criar citações em bloco que são renderizadas com cores e ícones que destacam a importância do conteúdo. Há suporte para os seguintes tipos de alerta:

> [!NOTE]
> Information the user should notice even if skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Essential information required for user success.

> [!CAUTION]
> Negative potential consequences of an action.

> [!WARNING]
> Dangerous certain consequences of an action.

Esses alertas têm a seguinte aparência no Microsoft Learn:

Bloco de notas

Observação

Informações que o usuário deve conseguir notar mesmo que esteja correndo o texto.

Bloco de dicas

Dica

Informações opcionais para ajudar um usuário a ter mais sucesso.

Bloco de importância

Importante

Informações essenciais necessárias para o sucesso do usuário.

Bloco de cuidado

Cuidado

Possíveis consequências negativas de uma ação.

Bloco de aviso

Aviso

Consequências perigosas de uma ação.

Extensão Markdown - Tabelas

Uma tabela é um arranjo de dados com linhas e colunas que consistem em:

• Uma única linha de cabeçalho
• Uma linha delimitadora que separa o cabeçalho dos dados
• Zero ou mais linhas de dados

Cada linha consiste em células que contêm texto arbitrário separado por pipes (|). Para maior clareza, recomenda-se também o uso de um pipe à esquerda e outro à direita. Os espaços entre os pipes e o conteúdo da célula são cortados. Os elementos em nível de bloco não podem ser inseridos em uma tabela. Todo o conteúdo de uma linha deve estar em uma única linha.

A linha de delimitadores consiste em células cujo único conteúdo são hífens (-), e, opcionalmente, dois pontos à esquerda ou à direita (:), ou ambos, para indicar o alinhamento à esquerda, à direita ou central, respectivamente.

Para tabelas pequenas, considere usar uma lista em vez disso. As listas são:

• Mais fácil de manter e ler
• Pode ser feito refluxo para caber dentro do limite de 100 caracteres de linha
• Mais acessível para usuários que usam leitores de tela para assistência visual

Para mais informações, consulte Tabelas seção de Referência de markdown para o Microsoft Learn.

Hiperlinks

• Os hiperlinks devem usar a sintaxe Markdown [friendlyname](url-or-path).

• O sistema de publicação suporta três tipos de links:

  • Links do URL
  • Links de arquivos
  • Links de referência cruzada

• Todos os URLs para sites externos devem usar HTTPS, a menos que isso não seja válido para o site de destino.

• Os links devem ter um nome amigável, geralmente o título do artigo vinculado

• Evite usar aspas invertidas, negrito ou outras marcações dentro dos colchetes de um hiperlink.

• Os URLs simples podem ser usados quando você estiver documentando um URI específico, mas devem ser colocados em aspas invertidas. Por exemplo:

  By default, if you don't specify this parameter, the DMTF standard resource URI
  `http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/` is used and the class name is appended to it.
  

• Use referências de links onde permitido. As referências de links nos parágrafos tornam os parágrafos mais legíveis.

  As referências de link dividem um link Markdown em duas partes:

  • a referência do link - [friendlyname][id]
  • a definição do link - [id]: url-or-path

Links do tipo URL

• Links de URL para outros artigos sobre learn.microsoft.com deve usar caminhos relativos ao site. A maneira mais simples de criar um link relativo ao site é copiar o URL do navegador e, em seguida, remover https://learn.microsoft.com/en-us do valor que você cola no markdown.
• Não inclua localidades em URLs nas propriedades da Microsoft (remova /en-us do URL) ou links da Wikipedia.
• Remova todos os parâmetros de consulta desnecessários do URL. Exemplos que devem ser removidos:
  • ?view=powershell-5.1 - usado para vincular uma versão específica do PowerShell
  • ?redirectedfrom=MSDN - adicionado à URL quando você é redirecionado de um artigo antigo para seu novo local
• Se você precisar criar um link para uma versão específica de um documento, deverá adicionar o parâmetro &preserve-view=true para a cadeia de caracteres da consulta. Por exemplo: ?view=powershell-5.1&preserve-view=true
• Nos sites da Microsoft, os links de URL não contêm extensões de arquivo (por exemplo, não há .md)

Links de tipo de arquivo

• Um link de arquivo é usado para vincular um artigo de referência a outro, ou de um artigo conceitual a outro no mesmo conjunto de documentos.
  • Se você precisar criar um link de um artigo conceitual para um artigo de referência, deverá usar um link de URL.
  • Se você precisar criar um link para um artigo em outro docset ou em vários repositórios, deverá usar um link de URL.
• Use caminhos de arquivo relativos (por exemplo: ../folder/file.md)
• Todos os caminhos de arquivo usam caracteres de barra (/)
• Inclua a extensão do arquivo (por exemplo, .md)

Links de referência cruzada

Os links de referência cruzada são um recurso especial suportado pelo sistema de publicação. Você pode usar links de referência cruzada em artigos conceituais para vincular a API do .NET ou a referência de cmdlet.

• Para obter links para a referência da API do .NET, consulte Usar links na documentação na Guia do Colaborador central.

• Os links para referência de cmdlet têm o seguinte formato: xref:<module-name>.<cmdlet-name>. Por exemplo, para criar um link para o Get-Content cmdlet no módulo Microsoft.PowerShell.Management.

  [Get-Content](xref:Microsoft.PowerShell.Management.Get-Content)

Link profundo

A vinculação profunda é permitida em links de URL e de arquivo.

• O texto âncora deve estar em letras minúsculas
• Adicione a âncora ao final do caminho de destino. Por exemplo:
  • [about_Splatting](about_Splatting.md#splatting-with-arrays)
  • [custom key bindings](https://code.visualstudio.com/docs/getstarted/keybindings#_custom-keybindings-for-refactorings)

Para saber mais, confira Usar links na documentação.

Extensões de código

Os intervalos de código são usados para trechos de código embutidos em um parágrafo. Use aspas invertidas simples para indicar um intervalo de código. Por exemplo:

PowerShell cmdlet names use the `Verb-Noun` naming convention.

Esse exemplo é renderizado como:

Os nomes de cmdlet do PowerShell usam a convenção de nomenclatura Verb-Noun.

Blocos de códigos

Os blocos de código são usados para exemplos de comandos, exemplos de código de várias linhas, linguagens de consulta e saídas. Há duas maneiras de indicar que uma seção de texto em um arquivo de artigo é um bloco de código: cercando-a com aspas triplas (```) ou recuando-o.

Nunca use recuo, pois é muito fácil errar e pode ser difícil para outro gravador entender sua intenção quando precisar editar seu artigo.

Os blocos de código vedados podem incluir uma marcação opcional que indica a sintaxe da linguagem contida no bloco. A plataforma de publicação oferece suporte a uma lista de marcações de linguagem. A marcação de linguagem é usada para fornecer destaque de sintaxe quando o artigo é renderizado na página da Web. A marcação de linguagem não diferencia maiúsculas de minúsculas, mas você deve usar minúsculas, exceto em alguns casos especiais.

• Os limites de código sem marcações podem ser usados para blocos de sintaxe ou outros tipos de conteúdo em que o realce de sintaxe não é necessário.
• Ao mostrar a saída de um comando, use um limite de código marcado com a marcação de linguagem Output. A caixa renderizada é rotulada como de Saída e não tem realce de sintaxe.
• Se a saída estiver em uma linguagem específica suportada, use a marcação de linguagem apropriada. Por exemplo, muitos comandos geram JSON, portanto, use a marcação json.
• Se você usar uma marcação de linguagem não suportada, o bloco de código será renderizado sem destaque de sintaxe. A marcação de linguagem torna-se o rótulo da caixa de código renderizado na página da Web. Coloque a marcação para que o rótulo fique em letras maiúsculas na página da Web.

Próximas etapas

Guia de estilo do PowerShell