Converter Markdown para Word na linha de comando (Pandoc)

Se você quer converter Markdown para Word na linha de comando, a resposta é pandoc, e o trabalho inteiro cabe em uma linha:

pandoc report.md -f gfm -o report.docx

Esse comando resolve a maioria dos documentos. O que os tutoriais de uma linha não contam é onde ele para de funcionar — e parte do que se escreve por aí sobre os limites do pandoc está simplesmente desatualizada. Rodei o pandoc 3.7.0.2 em um documento de teste recheado de tabelas, listas de tarefas, equações LaTeX e um diagrama Mermaid, e depois descompactei o .docx resultante para inspecionar o que de fato saiu. Alguns resultados me surpreenderam.

Este guia passa por instalação, os comandos que valem a pena conhecer, estilização do DOCX, conversão em lote e — com base nesse teste — um mapa honesto de onde o pandoc quebra e de quando um conversor online é a escolha melhor.

👉 Pular para os resultados do teste | Ir direto à comparação CLI vs online

Instalando o Pandoc

O pandoc é um binário único, com instaladores para todas as plataformas principais:

• macOS: brew install pandoc
• Windows: winget install --id JohnMacFarlane.Pandoc (ou o instalador MSI)
• Debian/Ubuntu: sudo apt install pandoc

Um alerta antes de confiar em um pacote antigo do sistema: os repositórios das distribuições costumam distribuir versões do pandoc com anos de atraso. O Ubuntu LTS entregou a 2.x por muito tempo, enquanto a linha de lançamento atual é a 3.x — e, como você verá abaixo, a idade da versão muda o que converte de forma limpa. Confira a sua com pandoc --version.

A conversão básica, explicada

O comando mínimo funciona, mas em projetos reais três flags fazem o trabalho pesado:

pandoc report.md -f gfm -o report.docx --toc

Por que -f gfm em vez do dialeto Markdown padrão do pandoc? Porque o Markdown que a maioria escreve hoje — em READMEs do GitHub, nas respostas do ChatGPT e do Claude, nas exportações do Notion — é GFM. O dialeto padrão do pandoc é mais acadêmico: habilita notas de rodapé e citações, mas interpreta algumas construções de outro jeito. Se a sua fonte veio de um assistente de IA ou de uma ferramenta de desenvolvedor, gfm é o leitor mais seguro.

Nota sobre matemática: com o leitor GFM, as fórmulas $...$ e $$...$$ simplesmente funcionam no pandoc atual. As equações viram equações nativas do Word, não imagens. Voltamos a isso mais abaixo, porque é o comportamento do pandoc mais mal reportado na web.

Estilizando a saída com um reference document

Um DOCX gerado pelo pandoc abre no Word com estilo genérico. Se o documento precisa seguir um template da empresa, você não resolve isso com flags — você usa um reference document.

O fluxo tem três passos:

1. Gere o template padrão do pandoc como ponto de partida:

   pandoc -o custom-reference.docx --print-default-data-file reference.docx
   

2. Abra o custom-reference.docx no Word e edite os estilos — Heading 1, Normal, Table, blocos de código. O conteúdo de texto desse arquivo é ignorado; só os estilos e a configuração de página são aproveitados.

3. Converta aplicando o template:

   pandoc report.md -f gfm --reference-doc=custom-reference.docx -o report.docx
   

O manual do pandoc documenta quais nomes de estilo são respeitados. O modelo mental que faz tudo encaixar: você não está estilizando um documento, está ensinando ao pandoc os estilos Word da sua organização uma única vez, para reutilizá-los em cada conversão.

Convertendo vários arquivos em lote

É aqui que a linha de comando vence de verdade qualquer ferramenta web. Para converter uma pasta inteira:

Bash (macOS/Linux):

for f in docs/*.md; do
  pandoc "$f" -f gfm -o "${f%.md}.docx"
done

PowerShell (Windows):

Get-ChildItem docs -Filter *.md | ForEach-Object {
  pandoc $_.FullName -f gfm -o ($_.FullName -replace '\.md$', '.docx')
}

E como o pandoc é uma dependência única, ele entra no CI sem cerimônia. Um step do GitHub Actions que regenera as cópias Word da sua documentação a cada push fica assim:

- uses: pandoc/actions/setup@v1
- run: |
    for f in docs/*.md; do
      pandoc "$f" -f gfm --reference-doc=brand.docx -o "out/$(basename "${f%.md}").docx"
    done

Equipes usam esse padrão para manter um espelho em Word de uma wiki em Markdown, para revisões de conformidade ou entregas a clientes. Se você converte o mesmo conjunto de arquivos mais de duas vezes, o script se paga na hora.

Onde o Pandoc encontra seus limites (testado no 3.7)

Este foi o teste que rodei. Um arquivo Markdown contendo uma tabela, uma lista de tarefas, matemática inline ($E = mc^2$), uma equação display de várias linhas, um flowchart Mermaid e um bloco de alerta GFM. Convertido com o pandoc 3.7.0.2; depois descompactei o .docx e li o word/document.xml diretamente. Três descobertas.

A matemática funciona melhor do que dizem por aí

O XML do documento contém dois blocos <m:oMath> — um por equação. Isso é OMML, o formato nativo de equações do Word. As duas equações são totalmente editáveis no editor de equações do Word, renderizam com qualidade de impressão e sobrevivem ao copiar e colar para outros documentos do Office.

Isso contradiz uma afirmação que você ainda encontra em tutoriais mais antigos (e, até pouco tempo atrás, em um dos nossos próprios guias): a de que LaTeX complexo seria rasterizado em imagens. No pandoc atual, não é. Matemática LaTeX padrão — frações, somatórios, letras gregas, subscritos — converte em equações nativas sem nenhuma configuração extra.

A fronteira honesta: o pandoc resolve a sintaxe matemática padrão do LaTeX, não LaTeX arbitrário. Macros personalizadas com \newcommand, figuras TikZ e ambientes que dependem de pacotes não fazem a viagem. E se a sua distro instalou o pandoc 2.x, o comportamento é outro — confira pandoc --version antes de culpar a ferramenta.

Mermaid é o verdadeiro ponto de ruptura

O flowchart Mermaid não virou diagrama. Ele passou como texto monoespaçado literal — o código-fonte flowchart LR cru, formatado como bloco de código. O XML do documento mostra zero objetos de desenho.

Isso importa mais agora do que há cinco anos, porque assistentes de IA adoram Mermaid. Peça ao ChatGPT ou ao Claude uma visão geral de arquitetura e há boa chance de a resposta incluir um bloco de código mermaid. Converta essa conversa com o pandoc e o seu documento Word vai conter o que parece código-fonte esquecido ali. Se esse é o seu fluxo, nosso guia sobre exportar a saída do ChatGPT para o Word cobre os detalhes específicos de IA.

Existe uma correção via CLI: o mermaid-filter, um filtro do pandoc que renderiza os diagramas durante a conversão. Funciona, mas pese o custo de configuração com honestidade — é um pacote npm que puxa um Chromium headless via Puppeteer, e a invocação vira pandoc -F mermaid-filter .... Para um pipeline de documentação que converte diagramas todo dia, esse custo se dilui. Para um relatório que vence hoje à tarde, é um desvio.

Pequenas perdas de fidelidade nas bordas

Duas descobertas mais discretas do mesmo teste. Blocos de alerta GFM (> [!NOTE]) mantêm o texto, mas perdem o destaque colorido — no Word eles aparecem como citações comuns. E os itens de lista de tarefas chegam como texto simples de lista, não como controles de caixa de seleção do Word. Nenhum dos dois quebra o documento; ambos achatam uma formatação que o autor provavelmente escolheu de propósito. Se a sua conversão dá errado de outras formas, catalogamos os modos de falha mais frequentes em problemas comuns na conversão de Markdown.

Linha de comando ou conversor online?

Depois desse teste, este é o critério de decisão que eu usaria de verdade:

Os dois caminhos são legítimos. O pandoc merece seu lugar em qualquer pipeline recorrente. Para o caso pontual de "preciso disso em .docx nos próximos cinco minutos" — principalmente quando há Mermaid no meio — um conversor online gratuito de Markdown para Word entrega um documento limpo com as equações e os diagramas renderizados, sem instalar nada.

Perguntas frequentes

P: Posso converter Markdown para Word sem instalar nada?
R: Não pela linha de comando — o pandoc exige instalação. Se instalar software não é uma opção, os conversores no navegador são o caminho prático; a conversão acontece no servidor e você baixa o .docx pronto.

P: O pandoc converte matemática LaTeX em equações reais do Word?
R: Sim. No meu teste com o Pandoc 3.7.0.2, tanto a matemática inline quanto a display viraram equações OMML nativas, editáveis no editor de equações do Word. As exceções são versões muito antigas do pandoc e macros LaTeX personalizadas.

P: Por que meu diagrama Mermaid aparece como código no Word?
R: O pandoc trata um bloco de código mermaid como código literal — ele não renderiza diagramas. Adicione o mermaid-filter ao seu pipeline (requer Node.js) ou use um conversor com renderização de Mermaid embutida.

P: Como mantenho as fontes e os estilos de título da minha empresa?
R: Use --reference-doc=template.docx. Edite os estilos desse template uma vez no Word; o pandoc os aplica em toda conversão. O conteúdo do template é ignorado, só os estilos são aproveitados.

P: Qual é a diferença entre -f markdown e -f gfm?
R: markdown é o dialeto estendido do próprio pandoc (notas de rodapé, citações); gfm corresponde ao que GitHub, ChatGPT e a maioria das ferramentas modernas produzem — tabelas, listas de tarefas, tachado. Para Markdown gerado por IA ou escrito por desenvolvedores, gfm traz menos surpresas.

P: O pandoc converte Word de volta para Markdown?
R: Sim — inverta os argumentos: pandoc report.docx -o report.md. A ida e volta perde parte da formatação específica do Word (caixas de texto, comentários), então trate como migração de conteúdo, não como um ciclo sem perdas.

Recursos relacionados

• O guia completo de Markdown para Word: o panorama completo das opções de conversão além da linha de comando
• ChatGPT para Word: o fluxo Markdown para documentos gerados por IA
• Markdown para PDF: quando a entrega precisa ser um PDF
• Problemas comuns na conversão de Markdown: correções para tabelas quebradas, problemas de codificação e desvios de formatação

Conclusão

O pandoc continua sendo a resposta certa para "converter Markdown para Word na linha de comando" — um comando para um arquivo, um script curto para uma pasta, --reference-doc para o estilo da empresa. No meu teste com o Pandoc 3.7, o suporte a matemática se mostrou melhor do que a fama: LaTeX padrão vira equações reais e editáveis do Word.

A lacuna genuína é visual: diagramas Mermaid chegam como código-fonte, a menos que você acople uma cadeia de filtros baseada em Node. Então escolha pelo fluxo de trabalho. Pipeline recorrente com documentos de texto puro: automatize com o pandoc. Documento único com diagramas e prazo: converta no navegador e mantenha equações e flowcharts intactos.

Referências

• Pandoc User's Guide — manual oficial: readers, writers, --reference-doc, tratamento de matemática
• Installing pandoc — instaladores oficiais para todas as plataformas
• mermaid-filter — filtro comunitário do pandoc para renderizar diagramas Mermaid
• pandoc/actions — GitHub Actions oficiais para pandoc em CI