Exportar markdown para docx usando o pandoc

Versão em vídeo: https://www.youtube.com/watch?v=R4kf6lqkSl8

Se você está trabalhando com documentações versionadas, uma das melhores saídas é o conjunto markdown + git. Assim, consegue controlar as edições de forma simples, e usando um mecanismo de formatação muito robusto.

E quando o time que não usa markdown precisa de acesso a estes documentos, e exige que seja enviado em formato doc ou docx, como fazer? É nesse momento que o pandoc entra em ação.

O pandoc é uma ferramenta de conversão de arquivos de texto para diferentes formatos, que funciona de forma extremamente simples. Como o exemplo abaixo:

pandoc restricoes.md -o restricoes.pdf

Convertemos o documento restricoes.md para o formato pdf de jeito rápido e simples.

Porém, quando usamos a conversão para o formato doc/docx, sempre nos deparamos com o problema da formatação. Isso porque não conseguimos, no markdown, informar qual a formatação aplicar para cada elemento, de forma padronizada.

Mas até para isso a solução é simples:

Primeiro, você gera o documento de referência da formatação, com:

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

Onde o reference.docx não precisa existir localmente, ele é apenas a referência que o pandoc vai usar.

Depois, você abre o arquivo de referência e altera as formatações como desejar. Neste ponto, é importante não alterar o conteúdo do arquivo, apenas a formatação dos itens. Pode mudar também o tamanho da página, da margem, e assim por diante.

Terminado isso, só efetuar a conversão do arquivo como necessário, informando o arquivo de referência no momento de fazer a conversão. Voltando no exemplo anterior, do arquivo restricoes.md:

pandoc restricoes.md -o restricoes.docx --reference-doc=custom-reference.docx

Essa ideia é interessante porque pode ser integrada, por exemplo, em um pipeline de geração de documentação sob demanda.