Nem todo documento de repositório precisa ser Markdown

A maioria dos times não tem um problema de documentação. Tem um problema de experiência de leitura escondido dentro de um fluxo de Git.

Markdown virou padrão por bons motivos. John Gruber descreveu Markdown como um formato de texto puro fácil de ler e fácil de escrever que vira HTML estruturalmente válido na página original do projeto: página original do Markdown. Esse ainda é o melhor argumento a favor de Markdown: ele é texto-fonte. O diff funciona bem. Agentes conseguem ingerir. Engenheiros conseguem revisar sem abrir o navegador. Ele encaixa no modelo de documentação como código que o Write the Docs descreve: versionamento, markup em texto puro, revisão de código e verificações automatizadas: [guia do Write the Docs](Write the Docs como código/).

Mas formato de fonte e formato de leitura não são a mesma coisa.

Essa diferença se perde dentro dos repositórios. O time escreve um plano de implementação, uma revisão de arquitetura, um relatório para público executivo, um brief de lançamento, um artefato de qualidade ou uma explicação de protótipo. O arquivo vive no git, então alguém escolhe .md. Aí o documento vira uma sequência de títulos, listas e tabelas que tecnicamente contém a resposta, mas não torna a resposta legível.

É nesse ponto que HTML/CSS não é decoração. É o meio.

O GitHub já mostra onde está a fronteira

As superfícies de repositório do GitHub são otimizadas para Markdown. READMEs aparecem automaticamente nas páginas de repositóriositório segundo a documentação do GitHub: documentação do GitHub sobre READMEs. GitHub Flavored Markdown dá tabelas, listas de tarefas, links automáticos e blocos de código. Isso é o formato certo para documentos de fonte.

Mas o GitHub também limita de propósito o controle visual arbitrário em Markdown renderizado. O README do github/markup diz que o GitHub sanitiza HTML renderizado, removendo coisas como tags de script, estilos inline e atributos class ou id: README do github/markup. A especificação de GitHub Flavored Markdown documenta uma extensão de Raw HTML bloqueado: especificação do GitHub Flavored Markdown. Isso não é o GitHub sendo chato. É o GitHub se recusando a deixar cada README virar um mini site inseguro.

Se o objetivo é legibilidade de fonte, use Markdown. Se o objetivo é fidelidade visual, README.md é o lugar errado para fingir que existe um site.

GitHub Pages existe para o segundo caso: HTML, CSS e JavaScript estáticos saindo direto de um repositório, opcionalmente por um processo de compilação, publicados como site: documentação do GitHub Pages. Docusaurus, MDX, mdBook, Sphinx, rustdoc e ferramentas parecidas existem pelo mesmo motivo. Documentações sérias costumam manter a fonte perto do código e renderizar um artefato humano mais rico.

Markdown é ótimo até o documento ter outro trabalho

Um README tem um trabalho: orientar um desenvolvedor.

Um guia operacional tem um trabalho: ajudar uma pessoa de operação a recuperar um sistema.

Uma regra de agente tem um trabalho: ser curta o bastante para o modelo não passar por cima da invariável.

Markdown é excelente para esses casos.

Mas alguns documentos de repositóriositóriositório têm outro trabalho. Eles precisam convencer, resumir, comparar ou criar julgamento compartilhado entre pessoas que não vão ler um diff cru. Um plano de adoção de AI não é só texto. Ele precisa de premissas, status, donos, riscos, evidências e uma ordem de leitura. Uma revisão de arquitetura precisa de hierarquia. Um relatório de qualidade precisa de evidências que o leitor consiga escanear. Um brief de lançamento precisa fazer o olho cair na decisão, não em mais um bullet ornamental.

Você consegue forçar tudo isso em Markdown. Times fazem isso todos os dias. Funciona do mesmo jeito que uma planilha pode virar CRM. Dá para fazer, mas o meio está brigando com você.

HTML/CSS dá ordem de leitura ao artefato

HTML/CSS deixa o artefato dizer: esta seção importa mais, isto é metadados, esta é a decisão, este é o receipt, esta tabela pode rolar, este aviso não é só mais um bullet, este documento foi feito para ser aberto por uma pessoa.

Fluxos assistidos por AI tendem a criar mais artefatos de repositóriositóriositório: planos, auditorias, notas de review, passagens de contexto, resumos de protótipo. Markdown mantém esses arquivos baratos de criar. Não torna automaticamente esses arquivos baratos de aprovar.

Essa diferença importa porque documentos de repositóriositóriositóriositório não são mais escritos só por humanos para outros engenheiros. Eles fazem parte de um loop operacional: um agente escreve, um humano decide, outro agente executa, um humano verifica. A etapa de verificação humana não pode ser uma parede de Markdown toda vez.

O debate na internet não é Markdown contra HTML

A versão útil do debate é mais simples: fonte contra artefato.

Os melhores exemplos não jogam Markdown fora. The Rust Book é escrito em um repositório e renderizado como livro HTML navegável; o mdBook se descreve como uma ferramenta de linha de comando que cria livros com Markdown e entrega uma apresentação limpa, navegável e customizável: documentação do mdBook. O Docusaurus diz para autores focarem no conteúdo e escreverem arquivos Markdown, enquanto a ferramenta entrega um site de documentação com versionamento, i18n, busca, React e MDX: documentação do Docusaurus. MDX se apresenta como Markdown para a era dos componentes porque às vezes prosa precisa de componentes: documentação do MDX.

Até os argumentos anti-Markdown são, na prática, argumentos contra semântica fraca. A crítica de Eric Holscher em 2016 aponta para os sabores de Markdown e os limites dele em documentação técnica: crítica de Eric Holscher. CommonMark existe porque Markdown precisava de uma especificação mais forte e compatível: CommonMark. O guia do Google ainda trata Markdown como padrão preferido para docs de developer e HTML como exceção quando Markdown não expressa a estrutura: guia do Google sobre Markdown.

• Markdown vence quando o texto-fonte precisa continuar simples, revisável, portátil, fácil de grep e amigável para agentes ou revisão de código.
• HTML/CSS vence quando a experiência de leitura é o entregável: hierarquia, layout, escaneabilidade, navegação e fidelidade visual mudam a compreensão.
• MDX ou geradores vencem quando você precisa dos dois: revisão da fonte e um produto de documentação mantido, deslocando o custo de conversão para o build em vez de cada leitor.

HTML avulso não é um novo padrão. Custa mais revisar, inspecionar diff, rodar lint e manter. Se o documento muda toda hora, mantenha uma fonte em Markdown ou MDX e gere o artefato de leitura. Use HTML/CSS standalone quando a saída é delimitada, feita para humanos e mais lida do que editada.

Performance depende principalmente de onde o conversão acontece

Existe também uma versão computacional desse argumento. Não é "HTML rápido, Markdown lento." Isso é raso demais.

A pergunta melhor é: onde acontece a conversão? Navegadores renderizam HTML e CSS nativamente. Markdown precisa virar HTML em algum lugar antes de o leitor receber uma página web normal. Esse trabalho pode acontecer no build, na request ou no navegador.

A compilação costuma ser o caminho limpo. A documentação do Next.js descreve geração estática como HTML gerado em tempo de compilação e reutilizado em cada requisição, com cache em CDN disponível: documentação do Next.js sobre geração estática. É o mesmo padrão por trás de muita ferramenta de documentação: escreva Markdown ou MDX como fonte, compile uma vez, entregue HTML/CSS estático como artefato.

Por requisição é onde o custo começa a pesar. Se cada visualização de página pede para o servidor carregar Markdown, converter, transformar, sanitizar, realçar sintaxe e renderizar HTML, você colocou trabalho de documentação dentro do tráfego do usuário. A documentação de renderização no servidor do Next.js deixa o contraste claro: SSR gera HTML em cada requisição em vez de uma vez no build: documentação do Next.js sobre renderização no servidor.

No navegador é o caminho mais suspeito. Markdown no navegador significa enviar um conversãor para o usuário e gastar CPU dele para transformar texto em DOM. Bibliotecas como Marked e markdown-it falam de velocidade e mantêm benchmarks porque converter Markdown é trabalho real: Marked e markdown-it. MDX adiciona outra camada: a documentação do pacote descreve compilação para JavaScript via @mdx-js/mdx: documentação do pacote @mdx-js/mdx.

A regra de performance é simples: mantenha Markdown barato como fonte, mas não faça todo leitor pagar a taxa Markdown-para-HTML em tempo de execução.

HTML/CSS estático não é magicamente mais leve se você enche o artefato de JavaScript de framework, fontes gigantes, hidratação no cliente, ruído de telemetria ou assets sem compressão. Mas um artefato HTML avulso e semântico tem um caminho de entrega bem chato: servir arquivo, converter HTML nativo, aplicar CSS, cachear forte. O caminho chato é o ponto.

Minha regra para repos agora

Eu não colocaria HTML em tudo. É assim que você cria um segundo front-end que ninguém pediu.

Mantenha Markdown para:

• README files.
• AGENTS.md e regras de ferramenta.
• specs duráveis, ADRs, runbooks e conceitos.
• qualquer coisa cujo consumidor principal seja engenheiro, agente, grep ou revisão de código.

Use HTML/CSS standalone para:

• planos voltados para humanos.
• relatórios executivos ou para partes interessadas.
• relatórios de revisão visual.
• protótipos e artefatos de design.
• resumos estratégicos em que layout muda compreensão.

E torne uma restrição inegociável: o artefato HTML precisa ser semântico e verificado. A orientação de acessibilidade da MDN é o evidência chata aqui: use os elementos HTML certos, rótulos, texto de link, títulos, tabelas e estrutura amigável a teclado: orientação de acessibilidade da MDN. Um artefato bonito e inacessível é só um PDF com passos extras.

Por que isso importa para times AI-native

AI empurra times para mais documentação, não menos.

Toda execução de agente quer contexto. Todo plano quer critério de aceite. Toda revisão quer evidência. Toda passagem de contexto quer um registro. A tentação é jogar tudo em Markdown porque Markdown é barato.

Fonte barata pode virar leitura cara.

Um repositório que trata todo documento como .md otimiza para quem escreve e para agentes. Um repositório que separa documentos de fonte de artefatos humanos otimiza para o loop inteiro: máquina lê, humano decide, máquina age, humano verifica.

Isso é Harness Engineering em miniatura. Não processo pelo processo. Uma fronteira.

Markdown é onde o repositório lembra.

HTML/CSS é onde o repositório explica.

Use os dois. O truque é não pedir que um formato faça os dois trabalhos.