md-to-pdf-exams: creando exámenes PDF en Markdown

El problema de trabajar en múltiples sistemas operativos

Como muchos profesores de informática, he ido saltando de un sistema operativo a otro. Pero en mi caso, me he quedado usando tres de normal: Windows, macOS y Fedora.

Si bien ser “multiplataforma” me ayuda a probar bien el desarrollo en Flutter, me ha obligado a buscarme soluciones que funcionen independientemente del sistema que esté usando en ese momento.

Durante muchos años, Microsoft Office fue mi herramienta principal para crear contenido para clase. Funciona perfectamente en Windows y macOS, pero cuando me pasé a Linux, las alternativas disponibles simplemente… no estaban a la altura, por decirlo así. LibreOffice es funcional, pero la compatibilidad y el resultado final no son comparables. ONLYOFFICE está bien, pero me ha dado también algún que otro problema si quieres compatibilidad entre sistemas operativos.

Hace aproximadamente un año encontré una solución para las presentaciones: MARP. Me permite crear presentaciones en Markdown que se exportan a PDF o HTML con resultados muy decentes. Algún día subiré mi plantilla personalizada, pero esa es otra historia.

Este curso me planteé un nuevo reto: necesitaba un sistema multiplataforma para crear exámenes. Después de rehacer mi libro completo usando LaTeX y Pandoc, vi claro el camino a seguir.

El nuevo sistema

Así surgió md-to-pdf-exams, una herramienta que convierte exámenes escritos en Markdown a PDF usando Pandoc y LaTeX. Lo más interesante del proyecto es que permite escribir el contenido de forma sencilla en Markdown y el sistema se encarga automáticamente del diseño y la maquetación (a lo que quiero dedicarle cero tiempo de normal).

Características principales

El proyecto incluye varias funcionalidades que lo hacen especialmente útil para docentes:

• Soporte bilingüe: puedes generar exámenes en español o inglés.
• Gestión de soluciones: las respuestas se pueden almacenar en documentos separados e inyectar automáticamente en el mismo PDF (por ejemplo, para dar el examen junto a la solución a los alumnos).
• Exportación “profesional”: usa lualatex y fuentes Liberation para un resultado consistente en todos los exámenes.
• Multiplataforma real: funciona en Ubuntu/Debian, Fedora/RHEL, Arch/Manjaro, macOS y Windows.

La base del proyecto es una plantilla LaTeX creada originalmente por Driss Drissi, a quien debo mencionar y dar crédito por el excelente trabajo de diseño original.

Cómo usar md-to-pdf-exams

Requisitos previos

Antes de empezar, necesitas tener instalado:

• Pandoc (versión 3.x o superior)
• Una distribución LaTeX con soporte para lualatex
• El paquete de fuentes Liberation

La documentación del repositorio incluye instrucciones detalladas de instalación para cada sistema operativo.

Mi recomendación: usa Docker para ello. Tengo pendiente subir el Dockerfile, pero mientras tanto puedes usar una imagen de LaTeX con Pandoc preinstalado, como texlive-full y luego instalar Pandoc dentro del contenedor.

Comandos básicos

Una vez instalado, usar la herramienta es muy sencillo. El proyecto incluye un script que simplifica el proceso:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Generar examen en español (por defecto)
./scripts/export.sh

# Generar examen en español con respuestas
./scripts/export.sh --answers

# Generar examen en inglés
./scripts/export.sh --lang en

# Generar examen en inglés con respuestas
./scripts/export.sh --lang en --answers

El flujo de trabajo es el siguiente:

1. Escribes el examen en Markdown usando cualquier editor de texto
2. Ejecutas el script correspondiente según tus necesidades
3. Obtienes un PDF profesional listo para imprimir o distribuir

Ejemplo práctico

Imaginemos que estás creando un examen de programación. En lugar de pelear con formatos de Word o diseños de LibreOffice, simplemente escribes:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

---
title: Ejemplo de examen
lang: spanish
answers: false
solutions-file: exam/solutions_es.md
department: Departamento de Matemáticas
preamble: >
  Resuelve cada ejercicio mostrando cada paso.
---

@q Operaciones básicas

1. Realiza \(18 + 7\).
2. Despeja la \(x\) en \(5x = 45\).

El sistema se encarga del resto: numeración, formato, márgenes, tipografía… Todo automático. Eso sí, toca tener la referencia de LaTeX para escribir fórmulas si quieres (o eso, o se lo pides a un LLM).

Lo que aún falta por pulir

Como todo proyecto en desarrollo, md-to-pdf-exams tiene áreas que necesitan mejorar. Igualmente, el proyecto cumple mis expectativas, así que si quieres mejorarlo, un PR siempre es bienvenido:

Gestión de imágenes

Todavía no he implementado la inserción de imágenes en los exámenes. Seguro que sale de una manera decente, pero necesito investigar diseños personalizados para manejar casos con 2-3 imágenes de forma “fancy”. Es una de las prioridades para las próximas versiones.

Ideas futuras que estoy valorando

Soporte para CSV: en lugar de Markdown, permitir usar archivos CSV con un formato particular. Esto podría ser especialmente útil para personas que no conocen la sintaxis Markdown, haciendo el proyecto más accesible.

Integración con LLM: implementar un sistema que convierta texto plano con fórmulas a Markdown usando un modelo de lenguaje, y luego exportar a Pandoc. Esto automatizaría aún más el proceso de creación.

Lo de siempre: ideas no me faltan. Lo que falta es tiempo para implementarlas todas.

Por qué Markdown + Pandoc + LaTeX

Por si no conocéis estas herramientas, para mí la combinación, aunque puede parecer compleja al principio, ofrece unas ventajas clarísimas:

Ventajas de escribir en Markdown

• Sintaxis simple: más fácil que aprender LaTeX completo.
• Portabilidad: archivos de texto plano que funcionan en cualquier sistema.
• Control de versiones: compatible con Git para trackear cambios.
• Enfoque en el contenido: no te distraes con el formato mientras escribes.

¿Qué hace Pandoc?

Pandoc es el conversor universal de documentos. Transforma Markdown a prácticamente cualquier formato: PDF, DOCX, HTML, LaTeX… En este proyecto lo usamos como intermediario entre Markdown y LaTeX.

LaTeX para la salida final

LaTeX sigue siendo el estándar para documentos académicos y científicos, ya que ofrece:

• Tipografía profesional
• Manejo excelente de fórmulas matemáticas
• Consistencia en el diseño
• Resultados reproducibles

Casos de uso reales

Desde que empecé a usar md-to-pdf-exams, mi flujo de trabajo ha mejorado significativamente:

• Creación rápida de exámenes: puedo escribir un examen completo en mi editor de texto favorito (uso VS Code con extensiones de Markdown) y generar el PDF en segundos.
• Versiones con y sin respuestas: con un simple flag --answers, genero la versión para los estudiantes y la versión con soluciones para mí (que me ayuda bastante a corregir rápido).
• Reutilización de contenido: al estar todo en texto plano, puedo reutilizar preguntas, reorganizarlas o modificarlas fácilmente, sin tener que estar modificando el formato todo el rato.
• Independencia del sistema: puedo crear el mismo examen en mi PC con Windows del trabajo, mi MacBook personal o mi PC con Fedora en casa. El resultado es idéntico.

Contribuye al proyecto

md-to-pdf-exams es un proyecto de código abierto disponible en GitHub. Si eres docente, desarrollador o simplemente te interesa el proyecto, hay varias formas de contribuir:

• Reporta bugs: si encuentras algún problema, abre una issue.
• Sugiere mejoras: todas las ideas son bienvenidas.
• Contribuye código: pull requests son más que bienvenidos.
• Comparte el proyecto: si te resulta útil, cuéntaselo a otros docentes.

El objetivo es crear una herramienta que ayude a la comunidad educativa a trabajar de forma más eficiente, independientemente del sistema operativo que utilicen.

Si tienes preguntas, sugerencias o quieres compartir cómo usas la herramienta, no dudes en contactarme o abrir un issue en el repositorio.