Passo a passo · 6 min de leitura
Sintaxe de Markdown: um guia prático
Markdown é uma forma de escrever documentos estruturados em texto simples. Você adiciona alguns sinais de pontuação ao redor do texto e um renderizador os transforma em títulos, listas, links, blocos de código e tabelas. O arquivo continua legível em qualquer editor de texto, e é por isso que READMEs, documentação, notas e rastreadores de issues o usam.
A sintaxe é pequena, mas as pequenas diferenças importam: uma linha em branco cria um parágrafo, os espaços decidem se uma linha vira item de lista, e um único underline dentro de uma palavra pode deixar metade dela em itálico. Este guia cobre a sintaxe que você usará todos os dias e os modos de falha que fazem a saída renderizada parecer errada.
O que Markdown é e o que não é
Markdown foi projetado como um formato de escrita que pudesse ser convertido em HTML, não como uma linguagem de descrição de páginas. Ele não tem conceito de fontes, margens, quebras de página ou posicionamento preciso; isso pertence à folha de estilos ou ao conversor de PDF que consome o HTML. Isso é uma vantagem: um arquivo Markdown continua legível em um terminal, em uma revisão de código ou em um e-mail de texto simples.
A sintaxe original não tem tabelas, listas de tarefas nem notas de rodapé. O GitHub Flavored Markdown (GFM) adicionou tabelas, blocos de código delimitados com indicação de linguagem, listas de tarefas, riscado e URLs com link automático, e a maioria das ferramentas modernas segue essa extensão. Se uma tabela aparece literalmente como barras e hífens, provavelmente o renderizador não suporta tabelas GFM, então consulte a documentação da ferramenta antes de reescrever o conteúdo.
A sintaxe que você vai usar todos os dias
A estrutura de blocos é controlada por linhas em branco. Parágrafos são separados por uma linha vazia; uma única quebra de linha costuma ser tratada como espaço, a menos que o renderizador suporte quebras forçadas. Títulos usam de uma a seis cerquilhas seguidas de um espaço, e o espaço é obrigatório em quase todas as implementações. Mantenha um único título de nível um por documento e construa uma hierarquia em vez de pular níveis.
A formatação embutida usa caracteres pareados: asterisco duplo ou underline para negrito, asterisco ou underline simples para itálico, crases para código embutido. Links são colchetes ao redor do rótulo seguidos de parênteses ao redor do destino, e imagens adicionam um ponto de exclamação antes dos colchetes. Citações começam com um sinal de maior que, e listas não ordenadas aceitam hífens, asteriscos ou sinais de mais desde que você seja consistente dentro de uma lista.
- Título: # Título, ## Seção, ### Subseção (espaço depois das cerquilhas).
- Ênfase: **negrito**, *itálico*, ***negrito e itálico***, `código embutido`.
- Link: [rótulo visível](https://example.com) e imagem: .
- Lista não ordenada: um hífen e um espaço por item; itens aninhados precisam de indentação consistente.
- Lista ordenada: 1. mais um espaço; o renderizador renumera automaticamente, então cada item pode começar com 1.
- Citação: > antes de cada parágrafo; separe blocos com uma linha em branco e outro >.
- Bloco de código: três crases, um nome de linguagem opcional, o código e três crases de fechamento.
Tabelas, código e sintaxe estendida
Uma tabela GFM precisa de uma linha de cabeçalho, uma linha separadora de hífens e dois-pontos opcionais para alinhamento, e depois linhas de dados. Cada linha precisa do mesmo número de barras, e uma barra faltando desloca uma coluna em silêncio. Blocos de código delimitados são mais seguros que blocos de código com indentação porque a delimitação sobrevive a copiar e colar e a indicação de linguagem ativa o realce de sintaxe.
Listas de tarefas adicionam um par de colchetes depois do marcador: um espaço para desmarcada e um x para marcada. Notas de rodapé e listas de definição são extensões que variam entre renderizadores, então evite-as quando o documento precisar sobreviver a uma conversão para PDF, a uma wiki ou a um e-mail. Na dúvida, teste o renderizador exato que o seu público usa em vez de supor que todo Markdown é idêntico.
Um fluxo de trabalho que mantém o Markdown legível
Escreva pensando primeiro na visão de texto simples. Mantenha as linhas razoavelmente curtas, separe as seções com linhas em branco e coloque os destinos dos links perto dos rótulos para que o código-fonte continue compreensível quando quebrar em um editor estreito. Use links relativos para arquivos do mesmo repositório e URLs absolutas para recursos externos; um link relativo para um arquivo renomeado vira um link quebrado que ninguém nota até um leitor clicar.
Pré-visualize enquanto escreve, principalmente depois de tabelas, listas aninhadas e blocos de código. Um editor ao vivo com prévia renderizada detecta uma linha em branco faltando antes que ela chegue a uma página de publicação. Quando converter Markdown para HTML ou PDF, mantenha o código-fonte sob controle de versão: a saída renderizada é descartável, enquanto o Markdown é o documento que você pode comparar e revisar.
Onde Markdown encaixa e onde não encaixa
Markdown é excelente para documentação, notas de versão, arquivos README, atas de reunião, artigos técnicos e tudo o que for guardado no Git. Encaixa mal em diagramação para impressão, design com precisão de pixels, tabelas complexas com células mescladas ou documentos que autores não técnicos precisam editar visualmente. Nesses casos, escreva em um processador de textos e exporte, ou use Markdown apenas como fonte intermediária e aplique uma folha de estilos ao HTML final.