O Markdown está te impedindo de avançar

• Markdown, amplamente usado para escrever documentação de desenvolvimento, é popular graças à sua simplicidade e acessibilidade, mas tem limitações em documentação técnica de grande escala por causa da falta de expressividade estrutural
• O Markdown funciona como um sistema de tipos implícito, o que impossibilita consistência ou validação por esquema, e também há problemas de compatibilidade entre diferentes variações (flavors) de Markdown
• Sintaxes estendidas como MDX aumentam a expressividade, mas acabam elevando a complexidade por causa da falta de portabilidade e padronização entre sistemas
• reStructuredText, AsciiDoc, DocBook e DITA oferecem estrutura explícita e marcação semântica (semantic markup), fortalecendo a reutilização e a interpretabilidade por máquinas
• Para documentos pequenos, Markdown é suficiente, mas para gestão de documentação em grande escala e multicanal, é necessário migrar para formatos estruturados

---

Limites estruturais do Markdown

• O Markdown, com sua sintaxe simples e fácil de ler por humanos, permite criar documentos visualmente agradáveis no GitHub ou em sites estáticos
  • No entanto, ele não consegue descrever o significado do conteúdo, então faltam informações estruturais compreensíveis por máquinas
• Motores de busca, LLMs, IDEs e agentes de IA aproveitam a estrutura semântica dos documentos, mas o Markdown gera apenas um conjunto limitado de tags HTML
• O Markdown também causa problemas de inconsistência ao reutilizar ou integrar conteúdo por causa das diferenças de sintaxe entre plataformas
• Como resultado, o Markdown é um formato de mínimo denominador comum, inadequado para gerenciar documentação complexa

O problema dos tipos implícitos no Markdown

• O Markdown é um formato sem esquema explícito nem definição de tipos, então o mesmo título ou lista pode ter significados diferentes dependendo do contexto
• Existem várias variações (flavors) de Markdown, o que gera diferenças de renderização entre ferramentas
  • Ex.: algumas ferramentas suportam notas de rodapé, enquanto outras as ignoram
• MDX amplia a expressividade ao inserir componentes React, mas tem baixa portabilidade por causa de problemas de compatibilidade entre sistemas
• Essas extensões tentam compensar as limitações do Markdown, mas são apenas soluções paliativas não padronizadas

A importância da marcação semântica

• Marcação semântica descreve o significado, e não a forma, do conteúdo
  • Ex.: “etapa (step)” e “item de lista” podem parecer iguais visualmente, mas têm significados diferentes
• O HTML5 introduziu tags baseadas em significado, como <section>, <article> e <aside>, reforçando a expressão estrutural
• Principais vantagens da marcação semântica
  • Transformação e reutilização: o mesmo conteúdo pode ser convertido em HTML, PDF, ePub e outros formatos
  • Interpretabilidade por máquinas: LLMs ou agentes conseguem reconhecer a estrutura com clareza e fornecer respostas mais precisas
• Como o Markdown não oferece essas informações estruturais, ocorre perda de informação em pós-processamento ou conversão

Comparação de formatos alternativos

• reStructuredText
  • Formato usado no Sphinx do ecossistema Python, que expressa significado estrutural por meio de diretivas (directive) e papéis (role)
  • Suporta elementos estruturais explícitos, como blocos de código, notas (note) e referências cruzadas (:ref:)
  • É adequado para documentação técnica de grande escala e suporta geração em HTML e PDF
• AsciiDoc
  • Um formato de texto semântico que oferece atributos (attribute), conteúdo condicional e recursos de include
  • Suporta expressões especializadas para documentação técnica, como avisos NOTE e WARNING, elementos de UI e notação de atalhos de teclado
  • Pode ser convertido em HTML, PDF, ePub, DocBook e outros formatos via AsciiDoctor
• DocBook (XML)
  • Um modelo baseado em XML para publicação técnica, com um sistema de tags semânticas como <command>, <note> e <xref>
  • Inclui tags necessárias para documentos especializados, como glossários, índices, elementos de UI e nomes de funções
  • Pode ser convertido em vários formatos de saída por meio de stylesheets XSLT
  • É vantajoso para validação estrutural de documentação em grande escala e geração de índices
• DITA (Darwin Information Typing Architecture)
  • Uma estrutura modular baseada em XML usada como padrão corporativo de documentação técnica
  • Como arquitetura XML orientada a tópicos, define claramente estruturas procedurais como <task> e <step>
  • É usada como padrão corporativo de gestão documental para reutilização de conteúdo (conref), filtragem e publicação multicanal
  • Suporta automação de renderização e conversão por meio do DITA Open Toolkit

Por que XML é necessário, mesmo parecendo incômodo

• O Markdown é leve, mas é uma solução temporária sem estrutura, padrão e consistência
• Se você está adicionando complexidade ao Markdown com MDX, plugins e scripts customizados,
  adotar de vez um formato estruturado é mais estável no longo prazo

Então, o que fazer?

• Para documentos pequenos, como README ou materiais pontuais, Markdown é suficiente, mas para documentação em grande escala, reutilizável e multicanal, reStructuredText, AsciiDoc, DocBook e DITA são mais adequados
• Se você precisa de documentos de planejamento, documentação para desenvolvedores, reutilização e gestão em grande escala, vale considerar na ordem reST/AsciiDoc → DocBook/DITA
• O ideal é usar como fonte o formato com a estrutura mais rica possível e, quando necessário, convertê-lo para Markdown
• O Markdown é útil como formato de saída, mas, se for usado como fonte da verdade (source of truth), a expansão estrutural se torna difícil
• O melhor é manter a fonte original em um formato rico em estrutura semântica e usar Markdown como saída downstream

[savvykang]

A realidade e os critérios de escolha de formatos baseados em XML
Para documentos pequenos, como README ou documentação pontual, Markdown é suficiente,
mas para documentação em grande escala, reutilizável e multicanal, reStructuredText, AsciiDoc, DocBook e DITA são mais adequados

rst é um formato baseado em XML? Nunca ouvi isso antes. O resumo está estranho.

[xguru]

Pelo resumo, parece que o título foi escrito assim ao falar dos critérios de escolha, agrupando-o com outros formatos XML. Corrigi para ficar de acordo com o original.

[jjw9512151]

Se precisar no Markdown, dá para usar HTML e anexar mermaid, então mais ou menos funciona... acima disso, parece que vira trabalho de documentação pela documentação.

[ahwjdekf]

As pessoas vêm antes da IA. Não roubem o que eu escrevi. Ficam falando de semântica, que bobagem.

[slowandsnow]

Se você acabar usando uma sintaxe especial, surge outra curva de aprendizado, além de precisar de ferramentas de parsing, visualizadores, editores etc. com suporte fluido... nesse nível, talvez seja melhor simplesmente usar Google Docs ou Notion, que conseguem se integrar bem com a maioria dos serviços de IA.

[GN⁺]

Opiniões do Hacker News

• O ponto central do Markdown é o amplo suporte que ele tem, algo que outras linguagens não têm A maioria das alternativas exige ferramentas próprias e não pode ser usada em ambientes onde Markdown já é suportado Até o Google Docs aceita colar Markdown como um recurso oculto Mesmo sem ser perfeito, a vantagem é “poder usar em qualquer lugar” Assim como o HTML era mais simples que o SGML, mas virou padrão porque os navegadores o suportavam, o Markdown também pode evoluir com o tempo A ambiguidade da padronização, a falta de recursos e os problemas de compatibilidade lembram a época do HTML4 Em vez de substituí-lo por completo, acho que o caminho mais realista é uma evolução gradual

  • Outra vantagem do Markdown é que qualquer pessoa consegue aprender em 5 minutos Já o introduzi para jornalistas de redação, e em um dia eles já achavam mais prático que o MS Word O atrativo era que o resultado saía exatamente como foi digitado, sem formatação complexa É um formato que até quem não é técnico aprende com facilidade
  • Acho que o Markdown já é o vencedor de fato Se o cliente quer Word ou PDF, eu envio assim, mas no fim quem decide o formato é o destinatário Para blocos de código, crases bastam, e tabelas ou diagramas mais complexos podem ser complementados com HTML
  • Uma característica importante do Markdown é que ele continua fácil de ler como texto puro É muito mais legível que LaTeX ou HTML Eu o vejo como uma linguagem de marcação de alto nível que compila para HTML Se necessário, também dá para misturar HTML diretamente
  • É verdade que o Markdown é amplamente usado, mas não existe nenhuma razão técnica que impeça outras linguagens Só que, por fatores sociais, a expansão é lenta Como ele não tem uma gramática sistemática como a do HTML, é difícil expandi-lo Já existem inúmeros dialetos de Markdown, mas a maioria fica restrita a poucas ferramentas O CommonMark é o que mais se aproxima de um padrão Mesmo que um sistema de extensões seja introduzido, acho baixa a chance de sucesso por causa de conflitos de sintaxe
  • O Markdown pode até evoluir, mas não existe autoridade central Há o CommonMark, mas ele é mais uma descrição técnica do que uma norma

• É possível incluir tags HTML em qualquer lugar no Markdown Isso está explícito na documentação oficial Portanto, a limitação mencionada pelo autor não existe na prática

  • Todo mundo sabe que dá para inserir HTML Mas o motivo de usar Markdown é justamente não precisar escrever HTML na mão Se eu tiver de ficar usando tags como ou o tempo todo, não há razão para usar Markdown Se no fim a resposta for “é só usar HTML”, então o próprio motivo de existir do Markdown desaparece
  • Na prática, não dá para misturar HTML e Markdown livremente Quando entra um bloco HTML, a sintaxe Markdown é desativada O AsciiDoc é bem mais flexível nesse ponto
  • Eu também uso Pandoc e Markdown, mas não pretendo voltar para AsciiDoc nem LaTeX Notas de rodapé e sumário também são suportados na maioria dos casos, e para trabalho baseado em texto comum isso já basta Não preciso de fórmulas nem de botões
  • Também existem plataformas como Reddit e GitHub que bloqueiam HTML por segurança Isso porque permitir HTML a usuários não confiáveis é perigoso
  • Eu também coloco elementos interativos em documentos Markdown No momento, porém, uso Markdown apenas para escrever conteúdo

• Na universidade, quando cursava física, escrevia artigos em LaTeX Em química usavam Word, então o padrão varia conforme a área A versão do TeX expressa o grau de completude desejado aproximando-se do valor de π A versão atual é 3.141592653, mantida de forma estável há 47 anos Veja a wiki do TeX e a explicação sobre a versão em Pi Para ferramentas de CLI, o formato de manpage também é útil

  • Aprendi a escrever documentos em LaTeX na graduação, mas hoje recomendaria mais o Typst Acho que ele é o sucessor mais promissor do LaTeX
  • Escrever documentos precisa ter pouco atrito O LaTeX tem uma barreira de entrada alta e é ineficiente por ser um formato mais voltado à composição tipográfica do que ao documento em si Documentos deveriam ser centrados no conteúdo, não na aparência
  • Eu fui o único que escreveu artigo usando Word Sofri para usar fontes do LaTeX e corrigir bugs de PDF, mas no fim deu certo Segundo pesquisas, usuários de LaTeX gastam mais tempo, mas têm maior satisfação com o processo Parece uma ferramenta para “pessoas que gostam do prazer de construir”

• O Markdown é como um produto mínimo viável (MVP) É fácil de aprender e continua legível mesmo sem renderização Para gerar PDF, migrei do AsciiDoc para o Typst, que resolveu problemas de acessibilidade Mas nenhuma linguagem de marcação melhora por si só a qualidade do texto Trocar de caneta não faz a escrita ficar melhor

  • Acho que o autor confundiu dois usos diferentes Markdown é para quem quer produzir conteúdo rapidamente Não é adequado para quem busca completude estrutural Provavelmente não existe uma linguagem que satisfaça plenamente os dois objetivos
  • A alternativa ao Markdown chamada Djot também é interessante Veja o link no GitHub
  • O LaTeX, ao exigir comentários por parágrafo, faz você pensar mais profundamente no texto
  • O Typst parece interessante, mas por enquanto só tem editor web e plugin para VSCode, então o ecossistema ainda é limitado

• O tom deste texto é o de que “o Markdown atrapalha o avanço dos LLMs” Mas a premissa de que seria possível obter riqueza semântica automaticamente não é realista Dentro das equipes, ninguém tem tempo para fazer esse tipo de trabalho, e Markdown já basta Como nas discussões sobre a web semântica, no fim a questão é quem vai manter os dados

• Eu escrevo meu blog com Org-mode + Emacs Gosto especialmente da função que permite ligar blocos de código e executá-los dentro do documento Já usei plataformas como Blorgit e lazyblorg, mas a configuração era trabalhosa, então exporto diretamente para HTML e envio ao servidor com rsync Depois adiciono um índice com um script Ruby e publico É muito mais expressivo e natural que Markdown

  • Se o Org-mode não fosse preso ao Emacs, acho que teria virado o formato padrão
  • Gostaria de perguntar se já experimentaram o Ox-Hugo É um excelente sistema para exportar arquivos Org para blogs Hugo
  • O Org-mode é integrado demais ao Emacs, o que dificulta a portabilidade Se surgisse um LSP, talvez pudesse ser usado em outros ambientes

• Concordo em parte com a ideia de que “o Markdown tem pouca estrutura”, mas acho uma pena essa abordagem binária Antes de escolher o formato, seria preciso entender primeiro que tipo de estrutura era necessária Por isso, o texto me incomoda um pouco e ao mesmo tempo é difícil concordar com ele

• Apresentar o DITA como alternativa ao Markdown é uma comparação completamente sem sentido DITA é um sistema XML corporativo de grande escala, com um objetivo totalmente diferente do Markdown Só faz sentido em ambientes com mais de 5 mil pessoas ou linhas de produto multilíngues Em qualquer contexto onde se use Markdown, DITA não será adequado Os dois acabam sendo perda de tempo

  • Eu não conhecia o DITA, mas achei engraçadíssimo o argumento “se Markdown é complicado, use XML”
  • Gostaria de ouvir mais sobre o DITA e seus casos de fracasso de toolchain

• Uso Markdown há mais de 10 anos e ele ainda funciona muito bem O argumento do texto também não está totalmente errado, mas não é um problema que usuários de Markdown sintam na prática Se precisar, é só usar outra coisa Ainda assim, o título era bom o bastante para eu gastar uns 5 minutos lendo

• É estranho mencionar o MyST como uma forma de Markdown e depois citar o reStructuredText (rST) como exemplo Afinal, o objetivo do MyST é justamente ser um substituto do rST A sintaxe é parecida com Markdown, mas ele também suporta significado estrutural, directives, roles etc. Há uma discussão relacionada na issue do Sphinx

[mstorm]

Vejo muitos textos desse tipo ultimamente.

Arquivo de texto, Markdown, formatos mais estruturados
Conforme isso vai mudando, não existe uma resposta certa; basta usar o formato adequado no momento adequado.

E, como sempre, tentar fazer tudo em um único arquivo acaba gerando problemas, então classificar e sistematizar de acordo com o tema é algo inevitável.