Guia Markdown: primeiros passos

Markdown é uma sintaxe de formatação em texto simples que transforma símbolos digitados em documentos estruturados, e aprender o essencial demora cerca de 10 minutos. John Gruber lançou-o em março de 2004 com o contributo de Aaron Swartz, e 22 anos depois formata ficheiros README no GitHub, notas no Obsidian e publicações no Reddit. Todo o sistema assenta em duas partes: um ficheiro de texto guardado com a extensão .md e um processador que converte esse texto em HTML. Tudo o que se segue parte destas duas partes.

O que é Markdown?

Markdown é uma linguagem de marcação leve de 2004 que acrescenta instruções de formatação ao texto simples através de carateres visíveis como #, * e >. Um # no início de uma linha cria um título. Dois asteriscos à volta de uma palavra colocam-na a negrito. Um hífen inicia um item de lista. A versão original era um único script Perl, o Markdown.pl, publicado no site Daring Fireball de Gruber.

As linguagens de marcação mais pesadas, entre elas HTML e LaTeX, envolvem o conteúdo em etiquetas e comandos que sobrecarregam o ficheiro em bruto. O Markdown seguiu o caminho oposto. Gruber desenhou a sintaxe com um único objetivo: um ficheiro Markdown deve ler-se de forma limpa como texto simples antes de qualquer conversão. A linha ## Pricing é claramente um título, mesmo para quem nunca ouviu falar de Markdown. Essa legibilidade explica porque o formato se espalhou dos blogues em 2004 para o GitHub em 2008, para o Stack Overflow em 2010 e para aplicações de notas como o Obsidian e o Joplin ao longo da década de 2010.

Em que difere o Markdown dos editores WYSIWYG

Um editor WYSIWYG como o Microsoft Word ou o Google Docs aplica a formatação através de botões da barra de ferramentas e esconde as instruções; o Markdown mantém cada instrução visível como carateres no ficheiro. WYSIWYG significa "what you see is what you get", ou seja, o que vê é o que obtém. No Word, seleciona uma frase, clica no botão Negrito e o ficheiro guarda essa decisão em XML binário que nunca chega a ver. Em Markdown, escreve **data de lançamento** e os dois pares de asteriscos são a formatação.

A diferença nota-se na hora de guardar. Um ficheiro .docx abre corretamente numa lista curta de programas, sobretudo Word, LibreOffice e Pages. Um ficheiro Markdown abre em qualquer editor de texto lançado desde a década de 1970, do Notepad ao vim e ao VS Code. Muitos editores Markdown eliminam a diferença visual com uma pré-visualização em tempo real em ecrã dividido: sintaxe em bruto no painel esquerdo, resultado renderizado no painel direito, atualizado a cada tecla. Obtém o feedback imediato do Word com a transparência do texto simples.

Porque se usa Markdown

Quem escreve escolhe o Markdown por quatro razões práticas: portabilidade, independência de plataforma, durabilidade e alcance. Todas elas decorrem da base em texto simples.

• Portabilidade. Um ficheiro Markdown circula entre aplicações sem conversão. Escreva um rascunho no iA Writer, edite-o no VS Code, publique-o através do Ghost. O ficheiro nunca muda de forma. Os 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 em Windows 11, macOS, Linux, iOS e Android. O ficheiro é texto UTF-8, pelo que uma nota escrita num telemóvel em 2026 abre byte a byte idêntica num computador.
• Durabilidade. O software morre; os ficheiros de texto sobrevivem. O WordPerfect dominava o processamento de texto em 1990 e hoje os seus ficheiros antigos são um projeto de recuperação. Um ficheiro Markdown de 2004 continua a abrir em menos de um segundo, o que conta para teses, contratos e manuscritos de livros com horizontes de 20 anos.
• Alcance. Plataformas como GitHub, GitLab, Reddit, Discord, Notion e Slack aceitam Markdown. Aprende-se a sintaxe uma vez e o investimento rende em todas elas.

Como funciona o processamento de Markdown

O Markdown torna-se um documento formatado através de um processo em 4 passos: escreve um ficheiro .md, um processador analisa-o, o processador gera HTML e um browser apresenta esse HTML. O processador, também chamado parser ou implementação, é o motor dentro de cada aplicação Markdown. Entre os processadores mais populares contam-se markdown-it, marked, cmark e Pandoc, e o cmark converte um documento típico em menos de 10 milissegundos.

Ferramentas diferentes expõem partes diferentes deste processo. Um editor online com pré-visualização em tempo real executa os passos 2 a 4 de forma invisível a cada tecla. Um gerador de sites estáticos como o Hugo executa o mesmo processo em centenas de ficheiros com um único comando de build. O processo em si nunca muda, e o HTML produzido combina com qualquer folha de estilos CSS ou converte-se depois em PDF, EPUB ou .docx com uma ferramenta como o Pandoc.

Para que serve o Markdown?

O Markdown cobre sete utilizações comuns: sites, notas, documentos, livros, apresentações, email e documentação técnica. A mesma sintaxe de 10 minutos cobre as sete.

Sites

Os geradores de sites estáticos como Hugo, Jekyll e Eleventy constroem sites inteiros a partir de pastas de ficheiros Markdown. O Jekyll, lançado em 2008, alimenta o GitHub Pages e o seu alojamento gratuito. As plataformas de conteúdos também aceitam Markdown: o Ghost tem um editor Markdown nativo e o WordPress aceita-o através do editor de blocos. Um artigo de blogue é um único ficheiro .md, e os sistemas de controlo de versões como o Git registam cada alteração feita nele.

Notas e documentos

As aplicações de notas como Obsidian, Joplin, Bear e Simplenote guardam cada nota como Markdown. O Obsidian, em particular, mantém cada vault como uma pasta de ficheiros .md no seu próprio disco, pelo que uma coleção de 5.000 notas continua pesquisável com ferramentas comuns. Para documentos avulsos, cartas, atas de reunião e trabalhos, um editor Markdown exporta diretamente para PDF ou HTML, e o PDF imprime-se, anexa-se a um email ou carrega-se em qualquer lado.

Livros e apresentações

O Leanpub transforma uma pasta de ficheiros Markdown num ebook acabado nos formatos PDF e EPUB, e o Pandoc faz o mesmo a partir da linha de comandos. Há autores que publicaram romances completos e livros técnicos de 300 páginas desta forma. Para diapositivos, ferramentas como o Marp e o Remark convertem um ficheiro Markdown numa apresentação, com um separador --- por diapositivo, muito mais rápida de rever do que um ficheiro PowerPoint com 40 diapositivos formatados à mão.

Email e documentação técnica

As extensões de browser como o Markdown Here convertem Markdown em email HTML formatado dentro do Gmail e de outros clientes de webmail. A 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 ficheiros .md. O Docusaurus, lançado pela Meta em 2017, acrescenta versionamento e pesquisa sobre simples páginas Markdown.

Variantes de Markdown: CommonMark e GFM

Uma variante ("flavor") de Markdown é uma versão específica da sintaxe, e as duas 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 limite por definir, como a indentação de listas aninhadas, pelo que os primeiros processadores divergiam no resultado. O mesmo ficheiro 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 análise em mais de 600 casos de teste. O Stack Overflow migrou a sua renderização para 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. Acrescenta cinco extensões: tabelas, listas de tarefas, texto rasurado, autolinks e blocos de código delimitados com etiquetas de linguagem. Quando a página de um produto afirma que "suporta Markdown", confirme qual a variante em causa, porque uma tabela GFM aparece como simples carateres de barra vertical numa ferramenta que só suporta CommonMark. O GFM é a escolha mais segura em 2026, e é a variante que o editor deste site renderiza.

Como começar a escrever em Markdown hoje

Abra um editor Markdown no browser, escreva um # seguido de um título e já escreveu o seu primeiro Markdown; não há nada para instalar nem conta para criar. Um editor de painel duplo mostra o resultado renderizado enquanto escreve, o ciclo de feedback mais rápido para aprender a sintaxe.

Comece pelos cinco elementos mais frequentes: # para títulos, **negrito**, *itálico*, - para listas e [texto](url) para ligações. Estes 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 guarde o resultado como ficheiro .md. A partir daí, o guia de sintaxe básica cobre os 9 elementos essenciais, e o guia de sintaxe estendida acrescenta tabelas GFM, notas de rodapé e listas de tarefas.

Perguntas frequentes

Preciso de instalar software para escrever em Markdown?

Um browser chega; um editor Markdown online trata da escrita, da pré-visualização e da exportação sem qualquer instalação. As aplicações para computador como Obsidian, iA Writer e VS Code, que qualquer utilizador pode transferir gratuitamente, acrescentam acesso offline e gestão de ficheiros locais quando forem precisas.

Que extensão usa um ficheiro Markdown?

Os ficheiros Markdown usam a extensão .md, com .markdown como alternativa menos comum. Ambas contêm exatamente o mesmo texto simples, e qualquer processador Markdown, do cmark ao Pandoc, aceita as duas.

Quanto tempo demora a aprender Markdown?

Os cinco elementos essenciais demoram cerca de 10 minutos, e a sintaxe básica completa de 9 elementos aprende-se numa única sessão. As extensões GFM, como tabelas e listas de tarefas, acrescentam mais 15 minutos. Compare com o LaTeX, onde uma formatação competente exige semanas.

Qual é a diferença entre CommonMark e GFM?

O CommonMark é a especificação base de 2014 que padroniza a análise essencial do Markdown, e o GFM é o superconjunto do GitHub de 2017 que acrescenta tabelas, listas de tarefas, texto rasurado, autolinks e blocos de código delimitados. Todo o documento CommonMark válido é também GFM válido, pelo que escrever em GFM é a escolha prática.