Partilhar via

As melhores práticas de markdown

Este artigo fornece orientações específicas para o uso do Markdown em nossa documentação. Não é um tutorial para Markdown. Se você precisar de um tutorial para Markdown, consulte este cheatsheet Markdown.

O processo de compilação que constrói a nossa documentação utiliza o markdig para processar os documentos em Markdown. Markdig analisa os documentos com base nas regras da especificação CommonMark mais recente. O OPS segue a especificação CommonMark e adiciona algumas extensões para recursos específicos da plataforma, como tabelas e alertas.

A especificação CommonMark é mais rigorosa sobre a construção de alguns elementos Markdown. Preste muita atenção aos detalhes fornecidos neste documento.

Usamos a extensão markdownlint no VS Code para impor nossas regras de estilo e formatação. Esta extensão é instalada como parte do Learn Authoring Pack.

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

Linhas em branco também sinalizam o fim de um bloco no Markdown.

  • Coloque um único espaço em branco entre blocos Markdown de diferentes tipos; 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 em HTML, portanto, as linhas em branco extras são desnecessárias.
  • Não use colocar várias linhas em branco consecutivas em um bloco de código, linhas em branco consecutivas quebram o bloco de código.

O espaçamento é significativo no Markdown.

  • Remova espaços extras no final das linhas. Os espaços à direita podem alterar a forma como o Markdown é renderizado.
  • Utilize sempre espaços em vez de tabs (tabs rígidos).

Títulos e cabeçalhos

Use apenas cabeçalhos ATX (# estilo, em vez de = ou - estilo).

  • Use maiúsculas e minúsculas - apenas os nomes próprios e a letra inicial de um título ou cabeçalho devem ser maiúsculos.
  • Inclua um único espaço entre o # e a primeira letra do título
  • Coloque uma linha em branco antes e depois dos cabeçalhos.
  • Não utilize mais do que um H1 por documento
    • Deve ser o primeiro cabeçalho
    • Deve corresponder ao título do artigo
  • Incrementar níveis de cabeçalho em um - não pule níveis
  • Limitar a profundidade a H3 ou H4
  • Evite usar negrito ou outra marcação nos cabeçalhos

Limitar o comprimento da linha a 100 caracteres

Para artigos conceituais e referência de cmdlet, limite as linhas a 100 caracteres. Para about_ artigos, limite o comprimento da linha a 79 caracteres. Limitar o comprimento da linha melhora a legibilidade de git diffs e histórico. Também torna mais fácil para outros escritores fazerem contribuições.

Use a extensão Reflow Markdown no VS Code para refluir parágrafos para ajustar o comprimento de linha prescrito.

Alguns tipos de conteúdo não podem ser facilmente refluídos. Por exemplo, o código dentro de blocos de código também pode ser difícil de refluir, dependendo do conteúdo e da linguagem de código. Não é possível refluir uma tabela. Nesses casos, use seu melhor julgamento para manter o conteúdo o mais próximo possível do limite de 100 caracteres.

Ênfase

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

  • Use ** para negrito
  • Utilizar _ para itálico

Seguir esse padrão torna mais fácil para outras pessoas entenderem a intenção da marcação quando há uma mistura de negrito e itálico em um documento.

Listas

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

Rodeie as listas com uma única linha em branco.

Listas não ordenadas

  • Não termine os itens da lista com um ponto, a menos que eles contenham várias frases.
  • Use o caractere hífen (-) para marcadores de listas 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 subelementos debaixo de um item de marcador.

  • Primeiro item de marcador

    Frase explicativa do primeiro ponto.

    • Item de marcador filho

      Frase explicando a bala da criança.

  • Segundo item do marcador

  • Terceiro ponto da lista

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 reordenação de itens e uniformiza a indentação do conteúdo hierárquico.
  • 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 é processado da seguinte forma:

  1. Para o primeiro elemento, insira um único espaço após o 1. As frases longas devem ser passadas para a próxima linha e devem alinhar-se com o primeiro carácter após o marcador da lista numerada.

    Para incluir um segundo elemento, insira uma quebra de linha após o primeiro e alinhe as indentações. O recuo do segundo elemento deve ficar ao nível do primeiro caractere após o marcador de lista numerada.

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

Imagens

A sintaxe para incluir uma imagem é:

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

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

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

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

Os seguintes tipos de arquivo de imagem são suportados: *.png, *.gif, *.jpeg, *.jpg, *.svg

Extensão Markdown - Caixas de alerta

O Learn Authoring Pack contém ferramentas que suportam recursos exclusivos do nosso sistema de publicação. Os alertas são uma extensão Markdown para criar blockquotes que são renderizados com cores e ícones destacando a importância do conteúdo. Os seguintes tipos de alerta são suportados:

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

Estes alertas têm esta aparência no Microsoft Learn:

Bloco de notas

Observação

Informação que o utilizador deve notar, mesmo que esteja a ler superficialmente.

Bloco de Dicas

Sugestão

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

Bloco importante

Importante

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

Bloqueio de aviso

Atenção

Consequências potenciais negativas de uma ação.

Bloco de aviso

Advertência

Perigosas certas consequências de uma ação.

Extensão de Markdown - Tabelas

Uma tabela é uma organização de dados com linhas e colunas que consistem em:

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

Cada linha consiste em células contendo texto arbitrário separado por tubos (|). Uma barra vertical no início e no fim também é recomendada para clareza. Os espaços entre os tubos e o conteúdo da célula são cortados. Elementos de 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 delimitadora consiste em células cujo único conteúdo são hífens (-) e, opcionalmente, dois pontos à esquerda ou à direita (:), ou ambos, para indicar, respetivamente, o alinhamento à esquerda, à direita ou central.

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

  • Mais fácil de manter e ler
  • Pode ser ajustado para se adaptar ao limite de linha de 100 caracteres.
  • Mais acessível para usuários que usam leitores de tela para assistência visual

Para obter mais informações, consulte a seção Tabelas da referência de Markdown para o Microsoft Learn.

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

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

    • Links de URL
    • Links de arquivo
    • Ligações 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 backticks, negrito ou outra marcação dentro dos colchetes de um hiperlink.

  • URLs nuas podem ser usadas quando você está documentando um URI específico, mas devem ser incluídas em backticks. 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 link quando permitido. As referências de links dentro dos 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
  • Os links de URL para outros artigos devem learn.microsoft.com usar caminhos relativos ao site. A maneira mais simples de criar um link relativo ao site é copiar o URL do seu navegador e, em seguida, remover https://learn.microsoft.com/en-us do valor colado na marcação.
  • Não inclua localidades em URLs em propriedades da Microsoft (remover /en-us do URL) ou links da Wikipédia.
  • Remova todos os parâmetros de consulta desnecessários da URL. Exemplos que devem ser removidos:
    • ?view=powershell-5.1 - usado para vincular a uma versão específica do PowerShell
    • ?redirectedfrom=MSDN - adicionado ao URL quando você é redirecionado de um artigo antigo para seu novo local
  • Se você precisar vincular a uma versão específica de um documento, deverá adicionar o &preserve-view=true parâmetro à cadeia de caracteres de 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 .md)
  • Um link de arquivo é usado para vincular de um artigo de referência para outro, ou de um artigo conceitual para outro no mesmo docset.
    • Se você precisar vincular de um artigo conceitual a um artigo de referência, você deve usar um link de URL.
    • Se você precisar vincular a um artigo em outro docset ou em repositórios, você deve usar um link de URL.
  • Use caminhos de arquivo relativos (por exemplo: ../folder/file.md)
  • Todos os caminhos de arquivo usam caracteres de barra diagonal (/)
  • Inclua a extensão do arquivo (por exemplo, .md)

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 à API .NET ou à referência de cmdlet.

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

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

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

Ligações profundas

A vinculação direta é permitida em links de URL e de arquivos.

  • O texto âncora deve ser minúsculo
  • 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 obter mais informações, consulte Usar links na documentação.

Segmentos de código

As extensões de código são usadas para trechos de código embutidos dentro de um parágrafo. Use backticks únicos para indicar uma extensão de código. Por exemplo:

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

Este exemplo é renderizado como:

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

Blocos de código

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 três acentos graves (```) ou recuando-a.

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

Os blocos de código vedados podem incluir uma tag opcional que indica a sintaxe de idioma contida no bloco. A plataforma de publicação suporta uma lista de tags de idioma. A marca de idioma é usada para fornecer realce de sintaxe quando o artigo é renderizado na página da Web. A etiqueta de idioma não diferencia maiúsculas de minúsculas, mas deve-se usar minúsculas, exceto em alguns casos especiais.

  • Cercas de código sem tags podem ser usadas 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 uma cerca de código com a etiqueta de linguagem Output. A caixa renderizada é rotulada como Saída e não tem realce de sintaxe.
  • Se a saída estiver em um idioma suportado específico, use a marca de idioma apropriada. Por exemplo, muitos comandos produzem JSON, então use a json tag .
  • Se você usar uma marca de idioma sem suporte, o bloco de código será renderizado sem realce de sintaxe. A marca de idioma torna-se o rótulo da caixa de código renderizada na página da Web. Coloque a tag em maiúscula para que ela seja colocada em maiúsculas na página da Web.

Próximos passos

Guia de estilo do PowerShell

  • Last updated on