Guía Técnica para Convertir Markdown a Word con Pandoc

Pandoc es una herramienta de línea de comandos versátil para la conversión de formatos de documento. Esta guía detalla el proceso de transformar archivos Markdown en documentos Word (DOCX), con un enfoque en la personalización de estilos y el manejo de fuentes.

Requisitos del Sistema

Se asume un entorno Linux con Homebrew instalado. Los archivos de ejemplo son documento_entrada.md y documento_salida.docx.

Instalación de Pandoc

Instale Pandoc mediante el gestor de paquetes de su sistema. En sistemas basados en Linux con Homebrew:

brew install pandoc

La instalación se realiza a nivel de usuario y agrega el comando al PATH del sistema.

Verificación de la Instalación

Para confirmar que Pandoc está correctamente instalado:

pandoc --version

Conversión Inicial sin Formato Específico

Para una conversión directa sin control de estilos:

pandoc documento_entrada.md -o documento_salida.docx

Aplicación de Resaltado de Sintaxis

Para incluir coloreado en bloques de código durante la conversión:

pandoc documento_entrada.md -o documento_salida.docx --highlight-style=tango

Configuración de Fuentes para Texto Multilingüe

Para asignar fuentes específicas a diferentes conjuntos de caracteres:

pandoc "documento_entrada.md" -o "documento_salida.docx" \
  -V mainfont="Times New Roman" \
  -V CJKmainfont="Microsoft YaHei" \
  --highlight-style=tango

La variable mainfont afecta al texto latino, mientras que CJKmainfont controla los caracteres CJK. Pandoc realiza la separación automáticamente mediante rangos Unicode.

Este método puede no aplicarse de manera uniforme a todos los elementos del documento, como títulos o tablas, debido a la jerarquía de estilos en Microsoft Word.

Control Avanzado mediante Plantillas DOCX

Para un dominio completo sobre el formato de salida, se recomienda el uso de plantillas personalizadas.

Creación de una Plantilla Base

Genere un archivo DOCX de referencia con los estilos predeterminados de Pandoc:

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

Es importante que el argumento de --print-default-data-file sea un nombre de recurso interno de Pandoc, como reference.docx.

Personalización de la Plantilla

Edite el archivo plantilla_base.docx con un procesador de textos y modifique los estilos esenciales:

• Estilo Normal: Defina la fuente para texto en inglés y en chino.
• Estilos de título (Heading 1, Heading 2, etc.): Asigne las mismas fuentes para consistencia.
• Estilo Code: Seleccione una fuente monoespaciada adecuada.
• Estilo de tabla predeterminado (Table Normal): Ajuste según sea necesario.

Ejecución de la Conversión con Plantilla

Utilice la plantilla modificada en el proceso de conversión:

pandoc documento_entrada.md -o documento_salida.docx \
  --reference-doc=plantilla_base.docx \
  --highlight-style=tango

Para emplear un archivo Word existente como plantilla, indique su ruta completa:

pandoc documento_entrada.md -o documento_salida.docx \
  --reference-doc="/ruta/completa/mi_documento_modelo.docx" \
  --highlight-style=tango

Comparativa de Enfoques

Automatización para Múltiples Archivos

Para procesar en lote todos los archivos Markdown en un directorio usando una plantilla:

for fuente in *.md; do
  nombre_base="${fuente%.md}"
  pandoc "$fuente" -o "${nombre_base}.docx" \
    --reference-doc=plantilla_base.docx \
    --highlight-style=tango
done

La misma lógica aplica al usar una plantilla personalizada, simplemente reemplace la ruta en el argumento --reference-doc.

Resolución de Problemas Habituales

Inconsistencias en la Visualización de Fuentes

Si los tipos de letra no se aplican de manera uniforme, la causa principle suele ser la prioridad de los estilos en Word sobre las variables de Pandoc. La solución consiste en utilizar una plantilla DOCX (--reference-doc).

Ausencia de la Fuente para Chino

En sistemas Linux, verifique la instalación de la fuente especificada:

fc-list | grep "Microsoft YaHei"

Si la fuente no aparece en la lista, proceda a instalarla manualmente.

Formato Incorrecto en Bloques de Código

El estilo responsable del formato de los bloques de código dentro de la plantilla DOCX se llama típicamente Source Code. Modifíquelo directamente en el archivo de plantilla.

Error de "Could not find data file"

Este mensaje de error se produce al intentar usar --print-default-data-file con una ruta de archivo personalizada en lugar de un nombre de recurso integrado. Para generar la plantilla base, utilice el comando correcto mostrado anteriormente. Para emplear plantillas personalizadas, utilice únicamente el parámetro --reference-doc.