Formato Markdown: guia completo para trabalhar com IA e automação

1. O que é Markdown: filosofia, CommonMark e por que é a língua nativa da IA

Markdown é uma linguagem de marcação de texto simplificada, criada por John Gruber em 2004 com um objetivo claro: escrever texto estruturado que permaneça altamente legível em sua forma bruta e seja facilmente convertido em HTML válido. O padrão moderno foi formalizado na especificação CommonMark e estendido pelo padrão GitHub Flavored Markdown (GFM).

Na interação com Inteligência Artificial (ChatGPT, Claude Code, Gemini, modelos locais via Ollama), o Markdown é a principal linguagem de comunicação.

Por que os Grandes Modelos de Linguagem "pensam" em Markdown

1. Economia ideal de tokens: Diferente do XML ou HTML, onde cada tag exige abertura e fechamento (<p>Texto</p>), o Markdown utiliza apenas marcadores mínimos ou quebras de linha simples.
2. Univocidade semântica: Os símbolos #, -, > e backticks não sobrecarregam a janela de contexto, fornecendo ao modelo um mapa claro da hierarquia das ideias.
3. Naturalidade para saída em streaming: A geração de texto palavra por palavra, sem tags complexas não fechadas, permite renderizar a formatação instantaneamente na interface do chat.
4. Controle de versão no Git: Arquivos .md são arquivos de texto simples, portanto, qualquer alteração na base de conhecimento ou documentação é facilmente rastreada via git diff.

2. Hierarquia de títulos e estrutura de navegação de documentos

Os títulos definem a espinha dorsal do documento e compõem o índice (Table of Contents). No Markdown, os níveis de título são indicados pelo símbolo de cerquilha (#) no início da linha — de um a seis.

Hierarquia de níveis de título no Markdown e as correspondentes tags HTML ЗбільшитиHierarquia de níveis de título no Markdown e as correspondentes tags HTML

Regra crítica do espaço após a cerquilha

De acordo com o padrão CommonMark, deve haver obrigatoriamente um único espaço entre o símbolo de cerquilha e o texto do título. Sem esse espaço, a maioria dos parsers modernos interpretará a entrada como uma hashtag comum ou texto bruto.

Comparação entre a escrita correta e incorreta de títulos ЗбільшитиComparação entre a escrita correta e incorreta de títulos

3. Formatação de texto: negrito, itálico, riscado e caracteres especiais

A ênfase inline ajuda a destacar termos e conceitos chave.

Sintaxe de destaque de texto em itálico no Markdown ЗбільшитиSintaxe de destaque de texto em itálico no Markdown

Nuances práticas de tipografia

• Destaque dentro de palavras: Para destacar parte de uma palavra, use sempre asteriscos (A*cat*meow), pois alguns processadores ignoram underscores dentro de palavras, interpretando-os como parte de identificadores de variáveis (user_profile_id).
• Quebra de linha sem novo parágrafo: Para adicionar uma quebra de linha (<br>) dentro de um mesmo parágrafo, coloque dois espaços no final da linha ou utilize a tag <br>.
• Comentários: Para notas que não devem ser renderizadas na página final, use a sintaxe de comentários HTML: <!-- Este é um comentário interno -->.

4. Listas e estruturas aninhadas: numeradas, com marcadores e checkboxes

As listas organizam algoritmos passo a passo e conjuntos de parâmetros.

Listas com marcadores e numeradas

Blocos adicionais dentro de listas

Para inserir um parágrafo, citação ou bloco de código dentro de um item de lista sem quebrar a numeração geral, faça um recuo de 4 espaços antes de cada linha filha:

2. Verifique o diretório de saída dist/.

6. Código inline, blocos de código e realce de sintaxe

Código e configurações exigem fonte monoespaçada e proteção contra interpretação de caracteres internos.

Código inline vs. Fenced code blocks

• Código inline: Backticks simples: git status.
• Escape de backtick dentro de código inline: Envolva com backticks duplos: `npm test`.
• Fenced code blocks: Três backticks com indicação obrigatória do identificador da linguagem.

7. Citações, callouts e divisores horizontais

As citações são criadas com o símbolo > no início da linha e são usadas para destacar pensamentos, avisos importantes ou citar textos.

Citações padrão e aninhamento multinível

GitHub Alerts modernos (Callout-blocks)

Plataformas modernas de documentação suportam blocos destacados padronizados com ícones coloridos:

Divisores horizontais

Três ou mais hífens (---), asteriscos (***) ou underscores (___) em uma linha separada criam uma linha horizontal:

8. Escaping de caracteres especiais e HTML embutido

Quando você precisa exibir um caractere de sintaxe Markdown como um sinal de pontuação comum, coloca-se uma barra invertida (\) antes dele.

Caracteres especiais da sintaxe Markdown que podem ser escapados com barra invertida ЗбільшитиCaracteres especiais da sintaxe Markdown que podem ser escapados com barra invertida

Lista de caracteres para escape

Uso seguro de HTML

Se o Markdown padrão for insuficiente, você pode usar tags HTML, mas lembre-se das limitações:

• Tag <br> para quebras de linha forçadas em tabelas.
• Tag <u> para texto sublinhado.
• Tags de bloco (<div>, <table>) devem ser separadas do código Markdown por linhas em branco, e a marcação Markdown não funciona dentro delas.

9. Tabelas GitHub Flavored Markdown (GFM) e diagramas Mermaid

As tabelas permitem comparar características, parâmetros e configurações.

Sintaxe de tabelas GFM com alinhamento

• :--- — Alinhamento da coluna à esquerda.
• :---: — Alinhamento centralizado.
• ---: — Alinhamento à direita (ideal para preços e números).

Visualização de arquitetura via Mermaid

Em vez de screenshots raster pesados, desenvolvedores modernos usam diagramas de texto integrados Mermaid:

10. Markdown em agentes de IA: CLAUDE.md, System Prompts e checklist de validação

Na era dos agentes autônomos de IA (Claude Code, Cursor, Windsurf, Devin), o Markdown tornou-se a principal linguagem para transmitir contexto de engenharia.

Arquivos de instrução do projeto (CLAUDE.md / .cursorrules)

Os agentes leem o arquivo raiz CLAUDE.md antes de cada requisição. Se ele estiver bem formatado, o modelo seguirá a arquitetura do projeto sem erros:

Master-prompt para gerar Markdown impecável

Checklist de qualidade do documento Markdown

• Não há tag # (H1) no corpo do artigo (o H1 é gerado exclusivamente a partir do título da página).
• Todas as seções de nível superior estão numeradas sequencialmente (## 1., ## 2.).
• Há sempre um espaço após os símbolos de cerquilha #.
• Todos os prompts, configurações e exemplos de código estão envolvidos nos blocos ``` apropriados.
• Caracteres especiais em links estão codificados no formato percent-encoding.
• Tabelas estão formatadas conforme o padrão GFM sem separadores danificados.
• Imagens possuem alt-text descritivo adequado.