Makefile para MarkDown y Pandoc

Hola,

Llevo un tiempo ya jugando con MarkDown para hacer documentación, porque es una forma muy sencilla y rápida de escribir. Su sintaxis es muy directa y fácilmente legible por las personas a diferencia de otros casos como LaTeX, que es una herramienta increíble, pero que deja un poco de mal sabor de boca por la cantidad de comandos que tiene.

MarkDown es realmente sencillo y no dispone de comandos complejos, pero permite hacer suficientes cosas para una documentación simple como formatear texto de forma simple, marcar secciones, hacer tablas, introducir código fuente con marcado de sintaxis, hacer listas numeradas o no numeradas, introducir imágenes y alguna cosa más, dependiendo del sabor1.

Ya hablé de lo que son los Makefiles y para qué valen. En este caso el Makefile convierte de MarkDown a PDF (make pdf) o a HTML (make html) o las dos (make all), de forma que se puede navegar por los archivos a través de hipervínculos y otras cosas.

Para la conversión se usa Pandoc, una pedazo de herramienta de conversión de archivos. También usa xelatex por debajo, que es uno de los motores de LaTeX para crear PDF (si no queréis hacer PDFs no os hace falta).

Os dejo con el Makefile, cualquier pregunta, comentario o duda me decís:

Para que funcione correctamente, necesitáis poner los diferentes archivos que queráis unir de forma ordenada, así:

.
├── Makefile
└── sections
     ├── 1_Introduction.md
     ├── 2_FirstSection.md
     └── 3_SecondSection.md

Y poco más, podéis editarlo al gusto y esas cosas, está bajo licencia WTFPL, así que… Lo que os dé la puta gana.

Para terminar, esta entrada ha sido escrita en Markdown, como muchas de las anteriores, y muchas de las que vendrán. 🙂

Saludos.


  1. El sabor significa que hay diferentes tipos de Markdown, que soportan más cosas o menos dependiendo de dónde se use. Por ejemplo, GitHub tiene un sabor de Markdown propio, que acepta cosas como TODO lists. Pandoc también tiene un Markdown un poco especial que acepta más cosas que otros (aunque creo que TODO lists no, por ejemplo). De todas maneras, lo básico se mantiene en todos los sabores. 
Anuncios

3 pensamientos en “Makefile para MarkDown y Pandoc

  1. GitHub Pages, Markdown y mi CV – Free Hacks!

  2. Hola, me parece muy interesante este post para novatos como yo.

    He intentado construir lo que has sugerido por 3 .rmd que he generado para hacer la prueba. Sin embargo, al llamar make desde terminal de Ubuntu me sale el mensaje de debajo:

    C=pandoc
    .DEFAULT_GOAL := all
    FLAGS = -3
    FLAGS += –toc
    FLAGS += -s
    SECTIONS = $(sort $(wildcard sections/*.Rmd))
    TARGET_HTML = test.html
    .PHONY: html
    html: $(TARGET_HTML)
    $(TARGET_HTML): $(SECTIONS)
    $(C) $(FLAGS) -o $@ $(SECTIONS)

    Makefile:8: *** las instrucciones comenzaron antes del primer objetivo. Alto.

    ¿Sabes a qué error se refiere? ¿Qué es lo que estoy haciendo mal?

    Muchas gracias por escribir este blog. A algunos nos ayuda mucho.

    Pau.

    • Hola,
      Pues no he investigado mucho pero el flag -3 no me lo reconoce mi versión de pandoc. Prueba eliminándolo.

      Por lo demás me funciona si pongo la indentación correcta.
      Por lo que he leido, este error suele aparecer cuando hay un espacio indeseado al iniciar alguna línea.

      Trata de no comenzar ninguna linea con espacios salvo la última que muestras, que debería comenzar con una tabulación.

      Así debería funcionar. Prueba y me dices si lo has conseguido. Si no, lo seguimos revisando.

      Saludos.

      PD: También añadir que has puesto all como default goal pero luego no lo has definido, sólo has puesto el goal html. Estaría guay que lo pusieras o, aunque fuera, pusieras “all: html”

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s