Recuo em Markdown: listas aninhadas, parágrafos e código

Para recuar uma sublista Markdown, alinhe o marcador abaixo do primeiro caractere do texto do item pai. Para - Principal, isso significa dois espaços. Para 1. Principal, significa três. O recuo controla a estrutura do documento, então adicionar espaços a um parágrafo normal pode ter um efeito muito diferente de alterar o recuo visual de um parágrafo no Word.

Comece com este exemplo no visualizador de Markdown:

- Documentos do projeto
  - Guia de instalação
  - Notas da versão
- Lista de verificação da revisão

O guia de instalação e as notas da versão devem aparecer abaixo do item de documentos do projeto. A lista de verificação da revisão deve permanecer no nível externo.

Conte a partir do conteúdo do item pai

Para itens comuns de lista escritos com um espaço após o marcador, use este guia de alinhamento:

É por isso que uma regra geral como "sempre use dois espaços" falha em listas numeradas. A documentação de listas aninhadas do GitHub ilustra o alinhamento em relação ao conteúdo do item pai, incluindo marcadores numéricos mais longos.

1. Prepare a publicação
   - Confirme o número da versão.
   - Atualize o registro de alterações.
2. Publique a documentação

Os marcadores aninhados têm três espaços no início. Se começarem na margem esquerda, iniciarão uma lista separada em vez de pertencer à primeira etapa numerada.

Ao trabalhar com um processador Markdown antigo, visualize o arquivo nele também. Os exemplos aqui seguem a análise no estilo CommonMark e o Markdown do GitHub; implementações antigas podem reconhecer blocos aninhados de maneira diferente.

Adicione um parágrafo dentro de um item da lista

Uma explicação mais longa não precisa de um marcador próprio. Deixe uma linha em branco e alinhe o novo parágrafo abaixo do texto do item:

1. Revise o guia de instalação.

   Confirme que uma pessoa nova consegue concluir a configuração sem
   abrir um documento interno.

2. Aprove as notas da versão.

O parágrafo explicativo pertence à primeira etapa. Suas duas linhas do arquivo-fonte aparecem em sequência, a menos que você adicione uma quebra de linha explícita.

Omitir os três espaços pode encerrar a lista numerada e transformar a explicação em um parágrafo comum. Isso também pode fazer a lista seguinte reiniciar a numeração em alguns fluxos de edição.

O mesmo padrão funciona com marcadores:

- Guia de instalação

  Inclua pré-requisitos, comandos de configuração e uma etapa de verificação.
- Notas da versão

Use um parágrafo separado quando a explicação contiver várias frases. Use uma sublista quando houver itens distintos que os leitores devam examinar individualmente.

Coloque código dentro de uma etapa numerada

O código delimitado torna visíveis os limites de um exemplo de comando. Aplique recuo ao delimitador de abertura, ao conteúdo e ao delimitador de fechamento para manter o bloco dentro do item da lista:

1. Verifique a versão instalada.

   ```sh
   node --version
   ```

   Registre o resultado nas notas de revisão.

2. Execute as verificações do projeto.

Aqui, o delimitador começa abaixo da primeira letra de Verifique. O parágrafo depois dele usa o mesmo alinhamento, então também permanece dentro da primeira etapa.

Se a próxima etapa numerada virar parte do bloco de código, inspecione o delimitador de fechamento. Se o código aparecer fora da lista, inspecione os espaços no início do delimitador. Veja o guia de blocos de código para rótulos de linguagem e crases literais.

Por que quatro espaços podem transformar texto em código

No nível externo do documento, depois de uma linha em branco, quatro espaços antes de uma linha podem criar um bloco de código com recuo:

Um parágrafo comum.

    Esta linha é exibida como código.

Essa é uma sintaxe intencional do Markdown, não um controle de recuo com defeito. A referência de blocos de código com recuo do CommonMark explica o papel do recuo e dos limites de bloco.

Uma linha com recuo logo após o texto de um parágrafo comum está sujeita a outras regras de análise, então inserir espaços não é uma forma confiável de criar um recuo visual de parágrafo. Dentro de listas, os espaços necessários também são relativos ao item que contém o bloco.

Para uma citação, use uma citação em bloco. Para texto comum que precise de recuo na primeira linha em um relatório final, mantenha o Markdown como um parágrafo normal e aplique a formatação de parágrafo no Word após exportar. Essas escolhas preservam o significado pretendido do conteúdo.

Prefira espaços ao depurar

Tabulações podem ocupar várias colunas na tela, e editores diferentes podem exibi-las com larguras diferentes. Se uma lista parecer alinhada no código-fonte, mas for exibida incorretamente, mostre os espaços em branco no editor e substitua as tabulações iniciais pelo número necessário de espaços.

Não substitua indiscriminadamente tabulações dentro dos exemplos de código. Neles, os espaços em branco podem fazer parte do próprio exemplo. Limite a limpeza aos marcadores Markdown e ao recuo de continuação que determinam a estrutura da lista ao redor.

Evite usar entidades repetidas de espaço inseparável para imitar uma lista aninhada. Isso pode fazer o texto parecer deslocado em uma prévia enquanto o documento subjacente continua sendo composto por parágrafos sem relação.

Verifique a estrutura antes de exportar para Word

Revise uma seção representativa que contenha um item pai, uma sublista, um segundo parágrafo e um bloco de código delimitado. No conversor de Markdown para HTML, uma lista realmente aninhada fica contida no item pai; apenas um deslocamento visual não estabelece essa relação.

Depois use o conversor de Markdown para Word e abra o DOCX. Confira se a numeração continua como esperado e se os comandos permanecem associados às etapas. Os estilos de lista do Word podem usar espaçamentos visuais diferentes dos do navegador, então avalie tanto a hierarquia quanto a aparência final do documento antes de compartilhá-lo.