Formatos de arquivo
O que é Markdown? Sintaxe, CommonMark e GFM
Markdown é uma linguagem de marcação leve que adiciona títulos, listas e links a um texto simples com poucos símbolos. Veja sua história, seus padrões e o que se mantém ao transformar arquivos MD em Word ou PDF.
Autor: Hemen Dönüştür Editör EkibiPublicado em: 8 min de leitura
Pense no README de um projeto de software, nas listas com títulos de um aplicativo de notas ou nas palavras que você deixa em negrito com asteriscos em um aplicativo de mensagens. Por trás de tudo isso está a mesma ideia: o Markdown. Markdown é uma linguagem de marcação leve que permite definir títulos, listas, links e tabelas acrescentando alguns símbolos simples a um texto comum. O arquivo continua legível em qualquer editor de texto, mas pode virar uma página HTML limpa, um documento do Word ou um PDF sempre que você precisar. Este artigo mostra como o Markdown surgiu, sua sintaxe básica, as diferenças entre CommonMark e GitHub Flavored Markdown e o que observar ao converter arquivos MD.
O que é Markdown?
Markdown é ao mesmo tempo um conjunto de convenções de escrita e o nome comum das ferramentas que convertem textos escritos com elas em HTML. Os arquivos costumam ser salvos com a extensão .md ou .markdown. Segundo seu criador, John Gruber, o objetivo principal do projeto é a legibilidade: um documento Markdown deve poder ser publicado como está, em texto simples, sem parecer marcado com tags ou instruções de formatação. Onde o HTML precisa de <strong>importante</strong>, o Markdown usa **importante**, e até a versão bruta se lê com naturalidade.
Um pouco de história
John Gruber criou o Markdown em 2004, com Aaron Swartz contribuindo como interlocutor para suas ideias. A sintaxe se inspirou em convenções do e-mail em texto simples (asteriscos para ênfase, hifens para listas) e em linguagens de marcação anteriores, como setext e Textile. A versão 1.0.1 do Markdown.pl, o script em Perl que Gruber publicou em seu site Daring Fireball, é datada de 17 de dezembro de 2004.
A descrição de Gruber, porém, era uma explicação por exemplos, e não uma especificação formal. Casos ambíguos (listas aninhadas, blocos de código recuados, mistura com HTML) levaram cada implementação a fazer suas próprias escolhas, e o mesmo texto passou a gerar resultados diferentes em ferramentas diferentes. Vieram duas grandes respostas:
- CommonMark (2014): uma especificação liderada por John MacFarlane que define o Markdown sem ambiguidades e o torna testável com centenas de exemplos. As primeiras versões saíram no outono (do hemisfério norte) de 2014; a versão atual é a 0.31.2, de 28 de janeiro de 2024. A especificação ainda não foi declarada 1.0.
- GitHub Flavored Markdown (GFM, 2017): a especificação formal do GitHub construída sobre o CommonMark. Ela acrescenta extensões como tabelas, listas de tarefas, texto tachado, links automáticos ampliados e, por segurança, a filtragem de algumas tags HTML brutas. A última especificação publicada é a 0.29-gfm, de 6 de abril de 2019.
O Markdown também ganhou reconhecimento na infraestrutura da internet: o RFC 7763, publicado em março de 2016, registrou o tipo de mídia (tipo MIME) text/markdown com um parâmetro opcional variant, que indica qual variante de Markdown o autor pretendia usar.
Principais variantes do Markdown
Além do CommonMark e do GFM, existem outras variantes difundidas. O RFC 7764, publicado junto com o RFC 7763, registrou várias delas e trouxe orientações de uso:
- Markdown Extra: uma extensão antiga que adicionou notas de rodapé, listas de definição e tabelas.
- MultiMarkdown: uma variante voltada à escrita acadêmica, com metadados, citações e referências cruzadas.
- Pandoc Markdown: a variante usada pelo conversor Pandoc, com muitas extensões para escrever livros e artigos.
Uma regra prática: se o seu documento usa só títulos, listas, links, código e tabelas simples, ele vai ficar igual em quase todo lugar. Se você depende de notas de rodapé, listas de definição ou tipos especiais de bloco, verifique qual variante o ambiente de destino aceita.
Sintaxe básica
A parte do Markdown que você usa no dia a dia se aprende em poucos minutos:
# Título de nível um
## Título de nível dois
Este parágrafo tem **negrito**, *itálico* e `código`.
- Lista com marcadores
- Segundo item
- Subitem recuado
1. Lista numerada
2. Segundo passo
[Texto do link](https://example.com)
> Citação
```
Bloco de código com várias linhas
```Tabelas e listas de tarefas, adicionadas pelo GFM, ficam assim:
| Formato | Extensão |
|--------|-----------|
| Markdown | .md |
| Texto simples | .txt |
- [x] Escrever o rascunho
- [ ] RevisarOs parágrafos são separados por linhas em branco. Uma quebra de linha simples é tratada como parte do mesmo parágrafo na maioria das implementações; para forçar uma quebra de linha, termine a linha com dois espaços. Também é possível escrever HTML diretamente dentro do Markdown. O CommonMark permite isso, mas ambientes como o GFM bloqueiam algumas tags por segurança.
Onde o Markdown é usado?
- Desenvolvimento de software: READMEs, changelogs e guias de contribuição, além de issues e comentários de revisão de código em plataformas como GitHub e GitLab.
- Documentação técnica: geradores de sites estáticos que criam sites a partir de arquivos Markdown.
- Anotações: muitos aplicativos de notas armazenam ou exportam as notas em Markdown.
- Plataformas de chat e comunidades: plataformas como Reddit e Discord usam variantes de Markdown.
- Escrita e publicação: geração de HTML, PDF, DOCX e EPUB a partir de uma única fonte em Markdown com ferramentas como o Pandoc.
- Ferramentas de IA: assistentes de IA baseados em chat costumam formatar as respostas em Markdown.
Pontos fortes e fracos
| Pontos fortes | Pontos fracos |
|---|---|
| Legível até na forma bruta | As variantes se comportam de forma diferente |
| Texto simples: pequeno, portátil, ótimo para controle de versão | Sem fontes, cores ou layout de página |
| Converte facilmente para HTML, PDF e Word | Sem tabelas complexas (células mescladas) |
| Aprende-se em minutos | As imagens ficam em arquivos separados |
| Não depende de nenhum programa | Erros de espaço e recuo mudam o resultado |
Quais programas abrem Markdown?
Como o Markdown é texto simples, ele abre em qualquer editor de texto, incluindo o Bloco de Notas e o TextEdit. Para uma pré-visualização formatada, você pode usar a pré-visualização de Markdown integrada ao Visual Studio Code ou editores dedicados como Obsidian e Typora. O GitHub e o GitLab exibem automaticamente os arquivos .md dos repositórios. Já o Word não abre Markdown como texto formatado, então é preciso converter o arquivo antes.
Problemas comuns e como resolvê-los
Uma lista ou um título não aparece formatado
O CommonMark exige um espaço depois do marcador de título: ## Título, e não ##Título. Uma lista logo após um parágrafo também costuma precisar de uma linha em branco entre os dois para ser exibida corretamente.
As linhas ficam emendadas
Uma quebra de linha simples não divide o parágrafo. Deixe uma linha em branco para começar um novo parágrafo ou termine a linha com dois espaços para quebrar a linha dentro do parágrafo.
Uma tabela funciona em uma plataforma, mas não em outra
As tabelas não fazem parte do Markdown original de Gruber nem do núcleo do CommonMark; elas vêm de extensões como o GFM. Verifique qual variante a plataforma de destino aceita.
Um parágrafo que começa com número vira lista numerada
Uma linha como "2024. foi um ano agitado" começa com algarismos e um ponto, então pode ser interpretada como lista. Escape o ponto com uma barra invertida (2024\.) para evitar isso.
Dicas para converter arquivos Markdown
No nosso conversor, os arquivos Markdown são enviados ao nosso servidor e excluídos em até 30 minutos. Para a leitura, usamos a biblioteca Markdig com CommonMark e extensões no estilo do GitHub (tabelas, listas de tarefas, notas de rodapé, links automáticos).
- Markdown para PDF e Markdown para Word mantêm títulos, listas, blocos de código, citações e tabelas com bordas. As caixas de seleção das listas de tarefas viram os caracteres ☑ e ☐ para continuarem visíveis no Word e no PDF. Por padrão, o texto usa uma fonte serifada de 12 pt, e os blocos de código, uma fonte monoespaçada.
- Markdown para HTML transforma um README em uma página web autossuficiente com a codificação de caracteres declarada.
- No sentido inverso, Word para Markdown, HTML para Markdown e PDF para Markdown geram Markdown compatível com o GitHub: títulos, negrito e itálico, listas, tabelas, links, blocos de código e citações são mantidos; fontes, cores e layout de página são descartados. Em tabelas sem linha de cabeçalho, a primeira linha vira o cabeçalho, porque as tabelas GFM exigem um. Parágrafos comuns que começam com número, como "1. Cláusula", são escapados para não virarem listas por acidente. O arquivo é salvo em UTF-8 sem BOM.
Perguntas frequentes
Como abro um arquivo MD?
Qualquer editor de texto abre. Para vê-lo formatado, use a pré-visualização do Visual Studio Code ou um editor de Markdown; se quiser lê-lo no Word, converta-o para DOCX.
Qual é a diferença entre CommonMark e GitHub Flavored Markdown?
O CommonMark define a sintaxe básica do Markdown com regras precisas. O GFM é um superconjunto que acrescenta extensões ao CommonMark, como tabelas, listas de tarefas, texto tachado e links automáticos ampliados.
Dá para fazer tabelas em Markdown?
Sim, com extensões como o GFM você pode escrever tabelas simples usando barras verticais e hifens. Para estruturas complexas, como células mescladas, use uma tabela HTML ou prepare o documento no Word.
Qual é a diferença entre Markdown e HTML?
Markdown é um formato de escrita mais simples, pensado para ser convertido em HTML. Ele não expressa tudo o que o HTML expressa, mas sua forma bruta é muito mais legível. Ainda assim, você pode escrever HTML dentro do Markdown quando precisar.
O Markdown tem um padrão oficial?
A descrição original de Gruber não é uma especificação formal. Hoje, a definição precisa mais aceita é o CommonMark, e o tipo de mídia text/markdown foi registrado pelo RFC 7763 em março de 2016.
Fontes
- John Gruber, Daring Fireball: Markdown
- CommonMark Spec (histórico de versões)
- GitHub Flavored Markdown Spec
- IETF RFC 7763: The text/markdown Media Type (março de 2016)
- IETF RFC 7764: Guidance on Markdown
- Wikipedia: Markdown (história, fonte secundária)
- Markdig: processador de Markdown compatível com CommonMark para .NET
