Guia Markdown: Primeiros Passos

Markdown é uma sintaxe de formatação em texto puro que transforma símbolos digitados em documentos estruturados, e o essencial leva cerca de 10 minutos para aprender. John Gruber lançou o formato em março de 2004, com a colaboração de Aaron Swartz, e 22 anos depois ele formata arquivos README no GitHub, notas no Obsidian e publicações no Reddit. O sistema inteiro tem duas partes: um arquivo de texto salvo com a extensão .md e um processador que converte esse texto em HTML. Tudo o que vem a seguir neste guia markdown se apoia nessas duas partes.

O que é markdown?

Markdown é uma linguagem de marcação leve criada em 2004 que adiciona instruções de formatação ao texto puro por meio de caracteres visíveis como #, * e >. Um # no início de uma linha cria um título. Dois asteriscos ao redor de uma palavra deixam o texto em negrito. Um hífen inicia um item de lista. A versão original era um único script em Perl, o Markdown.pl, publicado no site Daring Fireball, de Gruber.

Linguagens de marcação mais pesadas, como HTML e LaTeX, envolvem o conteúdo em tags e comandos que poluem o arquivo bruto. O markdown seguiu o caminho oposto. Gruber projetou a sintaxe com um objetivo claro: um arquivo markdown precisa ser legível como texto puro antes de qualquer conversão. A linha ## Preços é claramente um título até para quem nunca ouviu falar de markdown. Essa legibilidade explica por que o formato se espalhou dos blogs em 2004 para o GitHub em 2008, o Stack Overflow em 2010 e aplicativos de notas como Obsidian e Joplin ao longo dos anos 2010.

Como o markdown difere de editores WYSIWYG

Um editor WYSIWYG como o Microsoft Word ou o Google Docs aplica a formatação por botões da barra de ferramentas e esconde as instruções; o markdown mantém cada instrução visível como caracteres dentro do arquivo. WYSIWYG significa "what you see is what you get", ou seja, o que você vê é o que você obtém. No Word, o usuário seleciona uma frase, clica no botão Negrito e o arquivo grava essa decisão em XML binário que você nunca vê. No markdown, você digita **data de lançamento** e os dois pares de asteriscos são a própria formatação.

A diferença aparece na hora de salvar. Um arquivo .docx abre corretamente em uma lista curta de programas, principalmente Word, LibreOffice e Pages. Um arquivo markdown abre em qualquer editor de texto lançado desde os anos 1970, do Bloco de Notas ao vim e ao VS Code. Muitos editores de markdown reduzem a distância visual com uma pré-visualização ao vivo em tela dividida: a sintaxe bruta no painel esquerdo, o resultado renderizado no painel direito, atualizado a cada tecla. Você tem o retorno imediato do Word com a transparência do texto puro.

Por que as pessoas usam markdown

Escritores escolhem markdown por quatro motivos práticos: portabilidade, independência de plataforma, durabilidade e alcance. Cada um deles vem da base em texto puro.

• Portabilidade. Um arquivo markdown transita entre aplicativos sem conversão. Rascunhe um post no iA Writer, edite no VS Code, publique pelo Ghost. O arquivo nunca muda de forma. Formatos proprietários como .docx e .pages prendem o conteúdo ao ecossistema de um único fornecedor.
• Independência de plataforma. O markdown funciona de forma idêntica no Windows 11, macOS, Linux, iOS e Android. O arquivo é texto UTF-8, então uma nota digitada no celular em 2026 abre byte a byte idêntica no computador.
• Durabilidade. Softwares morrem; arquivos de texto sobrevivem. O WordPerfect dominava a edição de textos em 1990 e seus arquivos antigos hoje são um projeto de recuperação de dados. Um arquivo markdown de 2004 ainda abre em menos de um segundo, o que importa para teses, contratos e originais de livros com horizontes de 20 anos.
• Alcance. Plataformas como GitHub, GitLab, Reddit, Discord, Notion e Slack aceitam markdown. Aprenda a sintaxe uma vez e ela rende em todas elas.

Como funciona o processamento do markdown

O markdown vira um documento formatado por um fluxo de 4 etapas: você escreve um arquivo .md, um processador interpreta o texto, o processador gera HTML e um navegador renderiza esse HTML. O processador, também chamado de parser ou implementação, é o motor dentro de todo aplicativo de markdown. Entre os processadores populares estão markdown-it, marked, cmark e Pandoc, e o cmark converte um documento típico em menos de 10 milissegundos.

Ferramentas diferentes mostram partes diferentes desse fluxo. Um editor online com pré-visualização ao vivo executa as etapas 2 a 4 de forma invisível a cada tecla. Um gerador de sites estáticos como o Hugo roda o mesmo fluxo em centenas de arquivos com um único comando de build. O fluxo em si nunca muda, e o HTML gerado combina com qualquer folha de estilos CSS ou segue adiante para PDF, EPUB ou .docx com uma ferramenta como o Pandoc.

Para que serve o markdown?

O markdown dá conta de sete tarefas comuns: sites, notas, documentos, livros, apresentações, e-mail e documentação técnica. A mesma sintaxe de 10 minutos cobre as sete.

Sites

Geradores de sites estáticos como Hugo, Jekyll e Eleventy constroem sites inteiros a partir de pastas de arquivos markdown. O Jekyll, lançado em 2008, é a base do GitHub Pages e de sua hospedagem gratuita. Plataformas de conteúdo também aceitam markdown: o Ghost tem um editor de markdown nativo, e o WordPress aceita markdown pelo editor de blocos. Um post de blog é um único arquivo .md, e sistemas de controle de versão como o Git registram cada edição feita nele.

Notas e documentos

Aplicativos de notas como Obsidian, Joplin, Bear e Simplenote armazenam cada nota como markdown. Só o Obsidian guarda cada cofre como uma pasta de arquivos .md no seu próprio disco, então uma coleção de 5.000 notas continua pesquisável com ferramentas comuns. Para documentos avulsos, cartas, atas de reunião e trabalhos acadêmicos, um editor de markdown exporta direto para PDF ou HTML, e o PDF pode ser impresso, anexado a um e-mail ou enviado para qualquer lugar. O usuário também pode baixar o resultado e arquivar localmente.

Livros e apresentações

O Leanpub transforma uma pasta de arquivos markdown em um ebook finalizado nos formatos PDF e EPUB, e o Pandoc faz o mesmo pela linha de comando. Autores já publicaram romances completos e livros técnicos de 300 páginas assim. Para slides, ferramentas como Marp e Remark convertem um arquivo markdown em uma apresentação, com um separador --- por slide, o que é mais rápido de revisar do que um arquivo do PowerPoint com 40 slides formatados à mão.

E-mail e documentação técnica

Extensões de navegador como a Markdown Here convertem markdown em e-mail HTML formatado dentro do Gmail e de outros clientes de webmail. Documentação é o território natural do markdown: o GitHub renderiza um README.md no topo de cada repositório, e geradores como MkDocs, Docusaurus e Read the Docs constroem sites de documentação completos a partir de arquivos .md. O Docusaurus, lançado pela Meta em 2017, adiciona versionamento e busca por cima de páginas markdown simples.

Sabores de markdown: CommonMark e GFM

Um sabor de markdown é uma variante específica da sintaxe, e os dois que mais importam são o CommonMark, especificado em 2014, e o GitHub Flavored Markdown, especificado em 2017. A versão de 2004 de Gruber deixou casos extremos sem definição, como o recuo de listas aninhadas, então os primeiros processadores discordavam no resultado. O mesmo arquivo era renderizado de forma diferente em ferramentas diferentes.

O CommonMark resolveu isso. Publicada em setembro de 2014 por um grupo de trabalho que incluía John MacFarlane e Jeff Atwood, a especificação CommonMark fixa cada regra de interpretação em mais de 600 casos de teste. O Stack Overflow migrou sua renderização para o CommonMark em junho de 2020.

O GitHub Flavored Markdown, ou GFM, é um superconjunto estrito do CommonMark que o GitHub formalizou em março de 2017. Ele adiciona cinco extensões: tabelas, listas de tarefas, texto tachado, links automáticos e blocos de código cercados com identificação de linguagem. Quando a página de um produto diz que "suporta markdown", verifique qual sabor é, porque uma tabela GFM aparece como simples caracteres de barra vertical em uma ferramenta que só entende CommonMark. O GFM é o padrão mais seguro em 2026, e é o sabor que o editor deste site renderiza.

Como começar a escrever markdown hoje

Abra um editor de markdown no navegador, digite um # seguido de um título e pronto: você escreveu seu primeiro markdown; não há nada para instalar nem conta para criar. Um editor de painel dividido mostra o resultado renderizado enquanto você digita, o que é o ciclo de aprendizado mais rápido para a sintaxe.

Comece pelos cinco elementos mais usados: # para títulos, **negrito**, *itálico*, - para listas e [texto](url) para links. Esses cinco cobrem cerca de 90% da formatação do dia a dia. Pratique reescrevendo algo real, uma nota de reunião ou uma lista de tarefas, e depois salve o resultado como um arquivo .md. A partir daí, o guia de sintaxe básica cobre os 9 elementos essenciais, e o guia de sintaxe estendida adiciona tabelas GFM, notas de rodapé e listas de tarefas.

Perguntas frequentes

Preciso instalar algum programa para escrever markdown?

Um navegador é suficiente; um editor de markdown online cuida da escrita, da pré-visualização e da exportação sem instalar nada. Aplicativos para computador como Obsidian, iA Writer e VS Code acrescentam acesso offline e gestão de arquivos locais quando você quiser baixar um deles.

Qual extensão de arquivo o markdown usa?

Arquivos markdown usam a extensão .md, com .markdown como alternativa menos comum. As duas guardam texto puro idêntico, e todo processador de markdown, do cmark ao Pandoc, aceita qualquer uma delas.

Quanto tempo leva para aprender markdown?

Os cinco elementos essenciais levam cerca de 10 minutos, e a sintaxe básica completa, de 9 elementos, cabe em uma única sessão de estudo. As extensões do GFM, como tabelas e listas de tarefas, somam mais 15 minutos. Compare com o LaTeX, em que formatar com competência leva semanas.

Qual é a diferença entre CommonMark e GFM?

O CommonMark é a especificação base de 2014 que padroniza a interpretação central do markdown, e o GFM é o superconjunto de 2017 do GitHub que adiciona tabelas, listas de tarefas, texto tachado, links automáticos e blocos de código cercados. Todo documento CommonMark válido também é GFM válido, então escrever em GFM é a escolha prática.