Usando o pandoc

2026-09-26

Este post é mais uma visão geral do Pandoc. No fim dele a gente vai ter um PDF só, em vez de uma pilha de documentos.

o que é o pandoc

O pandoc é uma ferramenta pra transformar um documento de uma linguagem de marcação pra outra. No meio de vários processos a gente precisa converter ou mexer nesses documentos: documentos em markdown pra pdf, etc.

Imagina que você tem uns arquivos .tex ou .docx e quer juntar tudo num PDF! É uma das coisas que o pandoc faz.

O problema é: existem muitas ferramentas online que fariam isso, mas muitas têm problemas sérios de conformidade, e a gente não tem controle nenhum sobre o que aconteceria com os nossos documentos :)

antes de começar

O pandoc pode dar um pouco de medo se você não é acostumado com linha de comando, mas eu acho que vale a tentativa.

Se você tem medo de CLI e terminal, o pessoal do Software Carpentry fez o melhor tutorial que eu conheço pra aprender o básico de Bash.

começando

Em vez de apresentar as ferramentas, a gente vai aprender o básico pondo a mão na massa >:)

Eu preparei alguns documentos simples pra este tutorial, que você pode pegar neste repositório

introdução

Vamos fingir que os documentos que a gente acabou de baixar são os rascunhos que vamos entregar pro nosso Professor. Pra isso, vamos precisar juntar os rascunhos e gerar um artigo acadêmico.

Se você olhar dentro da pasta, vai ver o mapa do nosso caos atual:

• latexpaperfront.tex: A capa que a REVISTA exigiu (um cenário do mundo real: você tem um arquivo .tex e precisa convertê-lo).
• Front_page.md: A mesma capa, mas já traduzida pra markdown (o nosso estado "depois").
• draft.md: O rascunho de verdade, cheio do nosso texto brilhante e das citações.
• lorem-ipsum.md: Uma seção de mentira, só pra enfeitar.
• refs.bib: O nosso arquivo de bibliografia com as referências.
• journal.tex: A mesma capa, pronta pra ser um template: o .tex com $body$ onde vai o texto do artigo (a gente chega lá).
• reference.docx: Um docx que carrega a cara da revista (serifada, entrelinha 1,5, margem de 2,5cm), pra quando o entregável tiver que ser um docx.

instalando

Ok, vamos nessa!

A instalação depende do seu sistema operacional:

windows

Linux

MacOS

a forma do comando

Um comando básico no pandoc seria assim:

pandoc draft.md -o draft.docx

ou

pandoc draft.md -s -o draft.tex

O pandoc tem muitas flags, vamos explicar rapidinho as mais importantes:

flag	significado
-o	Saída pra um arquivo
-s	Standalone
-f	De
-t	Pra

Com as duas últimas, a gente poderia escrever um comando pra converter um dos nossos arquivos de markdown pra latex, e depois produzir uma saída em outro formato (digamos tex), assim:

pandoc draft.md -f markdown -t latex -s -o draft.tex

É só uma forma mais declarativa de fazer a mesma coisa, com o mesmo resultado.

Pergunta - como a gente converteria, com o que aprendeu, o rascunho pra um arquivo docx? Resposta

pandoc draft.md -o draft.docx

pandoc draft.docx -t markdown -s -o converted_back_draft.md

convertendo de volta um documento

Depois de converter o nosso rascunho pra docx, o que aconteceria se a gente convertesse de volta pra markdown?

se a gente usar cat converted_back_draft.md, vamos ver que as nossas referências voltam assim: \[@lorem2025\]. em vez de [@lorem2025]. e é bom ter isso em mente.

juntando (o que o PI pediu)

Pra juntar as nossas páginas, o YAML tem que vir do primeiro arquivo: quando o pandoc recebe mais de um arquivo, ele lê os metadados do primeiro, e é ali que moram o título, os autores e o resumo.

E a gente tem uma flag nova pra aprender: --citeproc, ou -C pra encurtar. É a flag que renderiza as citações, e a gente vai usar ela :)

Front_page.md -> pandoc
draft.md -> pandoc
refs.bib -> pandoc
pandoc -> LaTeX engine
LaTeX engine -> paper.pdf

O comando pra Misturar tudo num PDF só é:

pandoc Front_page.md draft.md -s --citeproc -o paper.pdf

Se você receber um erro parecido com este:

'pdflatex' not found. Please select a different --pdf-engine or install 'pdflatex'

É porque você não tem um motor Latex ou não especificou um (ou typst, se for o que você usa).

Se você já tem um, dá pra declarar assim: --pdf-engine=Seu_motor_aqui.

E o motor é uma ferramenta por conta própria: aquele draft.tex que a gente gerou antes compila sem pandoc no meio.

pdflatex draft.tex

ou

pdflatex latexpaperfront.tex

É o mesmo motor que o pandoc estava chamando pra gente, e é por isso que ele quer pacotes. Quando falta um, ele diz qual (a capa da própria revista para em File 'authblk.sty' not found numa instalação nova ou com um motor mais simples), e sudo tlmgr install <package> resolve. Pode ser que ele peça sudo tlmgr update --self em algum ponto.

Se você olhar o PDF agora, vai perceber que as referências não tiveram um lugar só delas. Pra isso, dá pra fazer de duas formas:

1. no YAML:

bibliography: refs.bib
reference-section-title: References

ou 2. no comando:

pandoc Front_page.md draft.md -s --citeproc -M reference-section-title=References -o paper.pdf

A flag -M ou --metadata serve pra especificar um campo de metadado no comando, e ela sobrescreve o que está escrito no arquivo também. Por exemplo, eu posso especificar um título novo pro meu artigo com -M title=new_title.

dando estilo

A capa da revista é um .tex, e a gente quer que o pandoc use ela. É isso que um template é: um arquivo LaTeX com $body$ onde vai o seu texto.

O repositório carrega o journal.tex: aquela mesma capa com o $body$ no lugar do texto do artigo. Entrega ele pro pandoc:

pandoc Front_page.md draft.md -s --citeproc -M reference-section-title=References --template=journal.tex -o paper.pdf

Eu sei que o comando parece enorme, mas se você olhar as flags, vai ver muitas que a gente já usou!

Todas as flags, uma por uma

Todas as flags do comando

flag	significado
-s	Standalone: o documento inteiro, não fragmentos.
--citeproc	Resolve as citações e anexa a lista de referências (-C pra encurtar).
-M reference-section-title=References	Um campo de metadado vindo da linha de comando: o título da lista de referências.
--template=journal.tex	A cara do documento: a capa da revista, com o $body$ onde vai o nosso texto.
-o	Pra onde a saída vai: paper.pdf.

E os dois arquivos do começo são as entradas, e o primeiro traz os metadados que o artigo usa: título, autores, resumo e a bibliografia.

Só isso, e todo artigo que você escrever sai com a cara que a revista pediu. Se você só quer cutucar um detalhe, o -H tweak.tex enfia linhas no cabeçalho do próprio pandoc. Outra coisa é o pandoc -D latex: ele despeja o template do próprio pandoc na tela, e ignora o -o sem reclamar, então nunca sai arquivo nenhum. E ele também não é o quadro inteiro: as macros que o writer dele emite, como \tightlist, não estão lá dentro.

Uma coisa pra esperar: o LaTeX vai pedir coisas que a capa nunca teve, e elas vêm em dois tipos. Um pacote que ele nomeia (longtable, pra uma tabela) está a um \usepackage de distância, ou um sudo tlmgr install <it> se o seu TeX for o pequeno. Uma macro que ele nomeia (\tightlist, pra uma lista apertada; CSLReferences, pra bibliografia) é o outro tipo: nenhum pacote vende ela, porque ela pertence ao template do próprio pandoc. É isso que um template tem que carregar, e é por isso que o journal.tex tem aquele bloco de definições dentro dele.

quando o Professor quer um docx

Você entregou o seu pdf pro Professor, mas ele decidiu entrar de férias, e o seu novo Orientador não trabalha com arquivos .tex: ele usa templates docx:

E quando a saída não é um PDF: docx, odt e pptx não são estilizados com um template, e sim com um documento de referência, onde você entrega pro pandoc um arquivo do mesmo tipo e ele copia os estilos de dentro dele (--reference-doc=reference.docx). O manual separa os dois trabalhos: o documento de referência ajusta os estilos, o template interpola os metadados. Entregar um template LaTeX pra um docx, por falar nisso, quebra o arquivo: o pandoc enfia o template dentro dele e ele deixa de ser um docx válido.

pandoc Front_page.md draft.md -s --citeproc -M reference-section-title=References --reference-doc=reference.docx -o paper.docx

pra onde ir agora

O material oficial mora ali, e é pra onde você vai quando este post acabar: o guia de primeiros passos e o MANUAL. Tem também o Pandoc for the people onde ele vai usar WASM pra rodar o pandoc no seu navegador (com uma GUI bem legal também, caso você tenha gostado da ideia do pandoc mas não do terminal).

E quando um artigo deixa de ser um artigo: o Quarto é um sistema de publicação baseado no pandoc, onde o mesmo markdown vira um livro, um site ou slides. Ele também traz templates de revista, pra quando a capa precisar parecer a da Nature.