Formatador Markdown

O que faz um formatador Markdown

O Markdown é tolerante. Você pode escrever um marcador de lista com -, * ou +, uma ênfase com * ou _ e um título com uma linha de sinais de igual ou com #. Essa liberdade é prática na hora de digitar, mas um arquivo editado por várias pessoas logo mistura todos os estilos. As tabelas saem do alinhamento, as linhas em branco somem e os diffs ficam poluídos.

Este formatador reescreve o código-fonte em um estilo único e consistente. Ele é baseado no Prettier, o formatador que a maioria dos projetos JavaScript já usa na documentação, então o resultado bate com o que o Prettier gera no VS Code ou na linha de comando.

Como usar

1. Cole seu Markdown na caixa da esquerda, ou clique em Abrir arquivo para carregar um arquivo .md. Colar já formata.
2. Clique em Exemplo se quiser ver um exemplo antes.
3. Escolha o Recuo, a Largura da linha e como fazer a Quebra de texto: Manter como está, Na largura da linha ou Uma linha por parágrafo.
4. Clique em Formatar (ou Ctrl e Enter) para rodar de novo depois de mudar alguma coisa.
5. Use Copiar ou Baixar para pegar o resultado. Limpar esvazia a entrada.

Depois de formatar uma vez, o resultado acompanha o que você digita.

Antes e depois

Este é um arquivo curto escrito em estilo misturado:

Project Notes
=============
* Install the tools
* Run the build
+ Deploy

|Name|Role|
|-|-|
|Ada|Admin|
|Linus|Editor|

Some *emphasis* and __bold__ text.

O formatador devolve:

Project Notes
=============

- Install the tools
- Run the build

* Deploy

| Name  | Role   |
| ----- | ------ |
| Ada   | Admin  |
| Linus | Editor |

Some _emphasis_ and **bold** text.

Algumas coisas aconteceram. Agora há uma linha em branco depois do título. A primeira lista usa -. O negrito usa ** e o itálico usa _. As colunas da tabela foram preenchidas para ficarem alinhadas no texto simples. Repare que “Deploy” ficou separado: ele usava outro marcador, então o Markdown o trata como uma segunda lista, e o formatador mantém esse sentido dando a ele um marcador diferente.

Quebra de parágrafos longos

Com Quebra de texto em Na largura da linha e largura de linha 60, este parágrafo:

Markdown files are easier to review when each paragraph follows the same rule for line length, because a diff then shows only the sentence that changed.

vira:

Markdown files are easier to review when each paragraph
follows the same rule for line length, because a diff then
shows only the sentence that changed.

Uma linha por parágrafo faz o contrário e junta de volta as linhas quebradas. Manter como está é o padrão seguro quando você não sabe o que a sua equipe espera.

O que ele deixa em paz

O formatador muda o layout, e não o significado. Algumas coisas ele não toca de propósito:

• Blocos de código. O código dentro de um bloco cercado fica exatamente como foi escrito. Um bloco marcado como js que contém const a={b:1} não é reformatado. Use o formatador JavaScript para isso.
• Listas numeradas. Se todos os itens começam com 1., ele mantém 1. em todas as linhas. Se você numerou 1, 2, 3, ele mantém assim.
• Texto que não é uma sintaxe válida. #Título sem espaço não é um título no CommonMark, então continua sendo um parágrafo comum. Acrescente o espaço e ele vira título.
• HTML embutido. As tags HTML dentro do seu Markdown ficam como estão.

Textos em português, com acentos e cedilha, passam sem mudança. A largura das colunas das tabelas é calculada pelos caracteres visíveis, então palavras como “Ação” ficam bem alinhadas.

Dicas

• Formate antes de fazer o commit. Arquivos consistentes fazem o diff de um pull request mostrar só as edições reais.
• Escolha uma regra de quebra para o repositório inteiro. Misturar arquivos com e sem quebra gera diffs enormes na primeira vez que alguém formata.
• Montar uma tabela à mão é lento. O gerador de tabela Markdown oferece uma grade para digitar e aceita colagens de planilhas.
• Precisa de Markdown a partir de uma página web ou de um arquivo do Word? Use a ferramenta de converter HTML para Markdown ou a de converter Word para Markdown e depois organize o resultado aqui.

Outras formas de formatar Markdown

• VS Code: instale a extensão do Prettier, abra um arquivo .md e use Formatar Documento. O resultado bate com o desta página.
• Linha de comando: npx prettier --write README.md formata um arquivo no próprio lugar. Acrescente --prose-wrap always para quebrar os parágrafos.
• Lint: o markdownlint confere regras de estilo como níveis de títulos e tamanho das linhas. Ele aponta os problemas, enquanto um formatador corrige o layout para você. Muitos projetos usam os dois.

Limites

O formatador segue o CommonMark com as extensões do GitHub, como tabelas e listas de tarefas. Extensões de outras ferramentas, como containers personalizados ou links de wiki, são tratadas como texto comum e podem ficar com um espaçamento diferente do que aquela ferramenta espera. O front matter no topo de um arquivo (o bloco entre duas linhas ---) é mantido. Arquivos muito grandes funcionam, mas a formatação demora mais porque tudo acontece no seu aparelho.